# 任务

比一次请求持续更久的工作：读取它的状态和结果。

API 参考。Base URL：`https://api.mirabase.dev`

## 读取任务

`GET /v2/jobs/{job_id}`

读取任务的状态、进度和结果：`ingest`、`reprocess` 或彻底删除产生的处理任务，树任务，或一次整理。树任务（`tjb_`）会报告 `progress`，并随进度给出 `result`。失败的树任务会保留已完成的部分：删除可以用 `result.delete_batch_id` 恢复，合并可以再次合并以完成其余部分。开启了离线整理的部署上，一次整理（`drm_`）的 `stage` 是 `memory.dream`，没有 `result`；报告用 [`GET /v2/memory/dreams/{dream_id}`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-read) 读取。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[文件与版本](https://mirabase.io/zh/developers/files.md#processing)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `job_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 响应

- `200` `application/json` `DevJob`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "id": "<id>",
  "kind": "processing",
  "status": "queued",
  "stage": "<stage>",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```

## 取消任务（即将上线）

`POST /v2/jobs/{job_id}/cancel`

> 尚未上线，接口和字段可能调整。

即将上线：在两批之间停止树任务。已完成的部分是保留还是撤销，尚未确定。

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `job_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 响应

- `200` `application/json` `DevJob`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "id": "<id>",
  "kind": "processing",
  "status": "queued",
  "stage": "<stage>",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```
