# Jobs

Work that outlives a request: read its status and result.

API reference. Base URL: `https://api.mirabase.dev`

## Read a job

`GET /v2/jobs/{job_id}`

Read a job's status, progress, and result: a processing job from `ingest`, `reprocess`, or a purge, a tree job, or a dream. A tree job (`tjb_`) reports `progress` and `result` as it goes. A failed tree job keeps what it already did: a delete restores with `result.delete_batch_id`, a merge continues with another merge. On deployments with memory dreaming enabled, a dream (`drm_`) has `stage: memory.dream` and no `result`; its report is [`GET /v2/memory/dreams/{dream_id}`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-read). Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Files and versions](https://mirabase.io/developers/files.md#processing)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `job_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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

## Cancel a job (Coming soon)

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

> This is not live yet. Endpoints and fields may change.

Planned: stop a tree job between chunks. Whether completed chunks stay or are undone is not decided yet.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `job_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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