# Entries

Entries reached by id: content, versions, processing, the trash, and erasure.

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

## List Entries

`GET /v2/entries`

Entries visible to the caller, optionally narrowed to one Space (`space_id`, which also takes `default` or `ext:<external_id>`). Memories and Agent profiles are not listed here. Ordered by id, descending; the order is stable while you page. `trashed=true` lists the trash instead: Entries that were deleted and can still be restored, each with `trash` (when it was trashed, and the path a file had). `q` and `state` narrow either list. A purged Entry is in neither list. A member with a `read_root` sees no trashed Entries. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |
| `space_id` | Query | `DevSpaceRef` | Optional | Keep the Entries of this Space. Accepts a Space id, `default`, or `ext:<external_id>`, as in a path. length 1..256 |
| `trashed` | Query | `boolean` | Optional | `true` lists the trash instead of the live Entries. |
| `metadata` | Query | `string` | Optional | Keep the Entries whose metadata has these values: a JSON object, URL-encoded, such as `{"status":"final"}`. Every key must match exactly; 1 to 8 keys. For a key that holds a list, the value must be one of them. |
| `q` | Query | `string` | Optional | Keep the Entries whose title or file path contains this, ignoring case: 1 to 200 characters, a literal match for browsing, not retrieval. To find Entries by meaning, call `search`. length 1..200 |
| `state` | Query | `DevKnowledgeState` | Optional | Keep the Entries whose `knowledge.state` is this, such as `failed` to list what processing gave up on. |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevEntry[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |

### 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/entries" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "title": "Launch notes",
      "latest_version_id": "<latest_version_id>",
      "metadata": {},
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z",
      "file": {
        "path": "/notes/hello.md",
        "size": 1,
        "media_type": "<media_type>",
        "etag": "<etag>"
      },
      "knowledge": {
        "state": "readable"
      },
      "memory": {
        "scope": "project",
        "kind": "<kind>",
        "pinned": false,
        "exclude": false
      },
      "memory_exclude": false,
      "access": {
        "role": "owner",
        "capabilities": [
          "knowledge:read"
        ]
      }
    }
  ]
}
```

## Read an Entry

`GET /v2/entries/{entry_id}`

Read one Entry: its `file` (path, size, media type, and ETag) when it has a path, `latest_version_id`, `metadata`, and `occurred_at`. Needs `knowledge:read`. Returns 404 `not_found` if the Entry does not exist or the caller cannot see it.

**Capability** `knowledge:read`

### Parameters

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

### Responses

- `200` `application/json` `DevEntry`

### 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/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}
```

## Update an Entry

`PATCH /v2/entries/{entry_id}`

Change an Entry's `title`, `metadata`, `metadata_patch`, `memory_exclude`, or `occurred_at`; send at least one. A new `title` writes a new version; the others do not. A file's title is its name: rename or move it with `tree/operations`. Needs `knowledge:write`.

**Capability** `knowledge:write`

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

### Parameters

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

### Request body

`application/json` `DevUpdateEntryRequest` A new title is a new version: the title is part of what gets indexed, and versions do not change. The same title does nothing. A file's title is its name, so `title` on a file returns 422: rename it with `tree/operations`. Send at least one field.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Optional | A new title, 1 to 512 characters. Not supported on a file: rename it with `tree/operations`. length 1..512 |
| `metadata` | `DevMetadata` | Optional | Replaces the Entry's metadata as a whole: send every key you want to keep, or `{}` to clear it. It does not create a version. Works on any Entry, a file included. Filters see the change once the Entry is reindexed, usually within seconds. |
| `metadata_patch` | `object` | Optional | Changes metadata key by key instead of replacing it: a key with a value is set, a key with `null` is removed, and the keys you do not mention stay. Two callers changing different keys do not overwrite each other. Not together with `metadata`. The result still holds at most 32 values. |
| `memory_exclude` | `boolean` | Optional | `true` retires the facts distilled from this Entry and stops distilling it; search and reading are unaffected. `false` distills it again, without restoring facts you previously forgot or corrected. |
| `occurred_at` | `string (date-time) \| null` | Optional | When the source itself happened. `null` clears it, and retrieval's time filter goes back to when the Entry was written. It does not make a version; filters see the change once the Entry is reindexed, usually within seconds. Memories already distilled keep the time they were given. |

### Responses

- `200` `application/json` `DevEntry`

### 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 PATCH "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}
```

## Move an Entry to the trash

`DELETE /v2/entries/{entry_id}`

Move an Entry to the trash. Requires `knowledge:write` and at least the `editor` role, the same as `DELETE files`; if the Entry is a file, its path moves to the trash with it. `restore` brings it back. A second delete returns 404 `not_found`.

**Capability** `knowledge:write`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `If-Match` | Header | `string` | Optional | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or `*`: returns 412 unless the file or Entry exists. Omit for last-write-wins. |

### Responses

- `200` `application/json` `DevFileDeletion`

### 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 DELETE "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "entry_id": "<entry_id>",
  "deleted": true
}
```

## Read an Entry's content

`GET /v2/entries/{entry_id}/content`

The same views as `GET files`, by id: `view=raw` (default) returns bytes, `meta` returns the Entry, and the rest return a content view. An Entry ingested from a URL has no raw bytes: `view=raw` returns 422 `view_not_available`; read `view=text` instead. With `view=raw`, `Range`, `If-Range`, and `If-None-Match` work as on `GET files`. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `view` | Query | `DevFileView` | Optional | Which form of the content to return: `raw` (the default) for its bytes, `meta` for the Entry, or `text`, `table`, or `recognized` for a processed view. |
| `version` | Query | `DevId` | Optional | The id of a version of this Entry to read instead of the latest. Not supported with `view=meta` (returns 422). length 1..256 |
| `Range` | Header | `string` | Optional | One range: `bytes=0-99`, `bytes=100-`, or `bytes=-100`. Applies to `view=raw` only; other views ignore it. |
| `If-Range` | Header | `string` | Optional | An `ETag`. If the content has changed, returns the full new content (200) instead of a range (206). |
| `If-None-Match` | Header | `string` | Optional | An `ETag` you already hold. With `view=raw`, returns 304 with no body if the bytes have not changed. |

### Responses

- `200` `*/*` `binary`, `application/json` `DevEntry | DevEntryContent`
- `206` `*/*` `binary`

### Response headers

- `ETag`
- `Mirabase-Entry-Id`
- `Mirabase-Version-Id`
- `Mirabase-Knowledge-State`
- `Last-Modified` When the content last changed, as an HTTP date. Only when the latest version is served.
- `Content-Range`
- `Accept-Ranges`

### Error statuses

`400` `401` `403` `404` `416` `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/entries/$ENTRY_ID/content" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}
```

## Get an Entry's download URL

`GET /v2/entries/{entry_id}/content-url`

A signed URL for the original bytes of `version` (default: the latest), valid for `expires_in` seconds (60 to 300, default 300). Same checks as `view=raw`; an Entry ingested from a URL returns 422 `view_not_available`. The access is audited before the URL is signed. An original kept on the server instead of in object storage returns 409 `content_url_unavailable`; read `view=raw` instead. 503 `original_unavailable` means the URL could not be signed right now: retry later. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `version` | Query | `DevId` | Optional | The id of the version to sign a URL for. Defaults to the latest. length 1..256 |
| `expires_in` | Query | `integer` | Optional | How long the URL stays valid, in seconds: 60 to 300, 300 by default. 60..300, default: 300 |

### Responses

- `200` `application/json` `DevContentUrl`

### Error statuses

`400` `401` `403` `404` `409` `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/entries/$ENTRY_ID/content-url" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "url": "https://example.com/article",
  "method": "GET",
  "expires_at": "2026-11-06T00:00:00Z",
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>"
}
```

## List copies (Coming soon)

`GET /v2/entries/{entry_id}/copies`

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

Planned: the Entries copied from this one that you can see, newest first.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevEntryCopy[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |

### 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/entries/$ENTRY_ID/copies" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "entry_id": "<entry_id>",
      "source_version_id": "<source_version_id>",
      "space_id": "<space_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## Diff versions

`GET /v2/entries/{entry_id}/diff`

Compare two versions of this Entry. `to` defaults to the latest. Returns 404 `not_found` if the version does not exist or you cannot see it. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `from` | Query | `DevId` | Required | The id of the version to compare from. length 1..256 |
| `to` | Query | `DevId` | Optional | The id of the version to compare to. Defaults to the latest. length 1..256 |

### Responses

- `200` `application/json` `DevVersionDiff`

### 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/entries/$ENTRY_ID/diff?from=<from>" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "entry_id": "<entry_id>",
  "from_version_id": "<from_version_id>",
  "to_version_id": "<to_version_id>",
  "identical": false,
  "basis": "original"
}
```

## Read lineage

`GET /v2/entries/{entry_id}/lineage`

Return where this Entry came from (created, copied, or merged from a branch) and how each version was created, newest first. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json` `DevLineage`

### 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/entries/$ENTRY_ID/lineage" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "entry_id": "<entry_id>",
  "origin": {
    "kind": "created"
  },
  "data": [
    {
      "version_id": "<version_id>",
      "parent_version_ids": [
        "<parent_version_ids>"
      ],
      "created_at": "2026-11-06T00:00:00Z",
      "kind": "create"
    }
  ]
}
```

## Read processing status

`GET /v2/entries/{entry_id}/processing`

Return the processing progress of the Entry's latest version: `status`, `knowledge_state`, the current `stage` with `progress` and, while it waits, `queue`; when it failed, `error`. Search finds the version once `stage` is `enriching` or `ready`. Poll this after a 202 from ingest, or send `Prefer: wait` on the write instead. For many files at once, poll [`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/developers/api/spaces.md#spaces-processing). `POST .../reprocess` retries a failed version. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

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

### Responses

- `200` `application/json` `DevEntryProcessing`

### 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/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "status": "accepted",
  "knowledge_state": "readable",
  "stage": "queued",
  "progress": {
    "done": 1,
    "total": 1
  }
}
```

## Erase an Entry

`POST /v2/entries/{entry_id}/purge`

Erase an Entry, live or trashed, with every version and its path. Cannot be undone. Needs `knowledge:manage` and the Space owner role. Storage quota is freed immediately; the job finishes the erasure.

**Capability** `knowledge:manage`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_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

- `202` `application/json` `DevJobReceipt`

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### 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/entries/$ENTRY_ID/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "job_id": "<job_id>"
}
```

## Reprocess an Entry

`POST /v2/entries/{entry_id}/reprocess`

Retry the latest version if it failed; otherwise, process it again. If processing is already in flight, returns 409 `job_in_flight` with its `job_id`. Needs `knowledge:write`.

**Capability** `knowledge:write`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_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

- `202` `application/json` `DevJobReceipt`

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### 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/entries/$ENTRY_ID/reprocess" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "job_id": "<job_id>"
}
```

## Restore an Entry

`POST /v2/entries/{entry_id}/restore`

Restore a trashed Entry and its path. If the path is occupied, returns 409 `path_conflict` without renaming anything. A purged Entry returns 409. An Entry that is not in the trash is returned unchanged. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Connect an Agent (MCP)](https://mirabase.io/developers/agents.md#tools)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_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` `DevEntry`

### 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/entries/$ENTRY_ID/restore" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}
```

## Revert to an older version

`POST /v2/entries/{entry_id}/revert`

Write the content of an older version as a new version. Without `If-Match` the last write wins. Reverting to the latest version does nothing. The response carries the new version's `ETag`, as a file write does. Needs `knowledge:write`.

**Capability** `knowledge:write`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_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 |
| `If-Match` | Header | `string` | Optional | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or `*`: returns 412 unless the file or Entry exists. Omit for last-write-wins. |

### Request body

`application/json` `DevRevertRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `DevId` | Required | The id of the version to revert to; its content becomes the new latest version. |

### Responses

- `200` `application/json` `DevEntry`

### Response headers

- `ETag` The `ETag` of what was just written: send it in `If-Match` on the next write without reading it again.

### 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/entries/$ENTRY_ID/revert" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"<version_id>"}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}
```

## List versions

`GET /v2/entries/{entry_id}/versions`

List the versions of an Entry, newest first. Needs `knowledge:read`.

**Capability** `knowledge:read`

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevVersion[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |

### 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/entries/$ENTRY_ID/versions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "<id>",
      "entry_id": "<entry_id>",
      "status": "accepted",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## Read a version

`GET /v2/entries/{entry_id}/versions/{version_id}`

Read one version of an Entry. A version's content never changes; its `status` does while it is processed. Returns 404 `not_found` if the version does not exist, belongs to another Entry, or cannot be seen by the caller. Needs `knowledge:read`.

**Capability** `knowledge:read`

### Parameters

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

### Responses

- `200` `application/json` `DevVersion`

### 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/entries/$ENTRY_ID/versions/$VERSION_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## Update a version message

`PATCH /v2/entries/{entry_id}/versions/{version_id}/message`

Replace the message of one version, at most 120 characters. The message is the only part of a version you can change. Only the Space owner can do this. Needs `knowledge:write`.

**Capability** `knowledge:write`

### Parameters

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

### Request body

`application/json` `DevUpdateVersionMessageRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Required | The version's new message, at most 120 characters. max length 120 |

### Responses

- `200` `application/json` `DevVersion`

### 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 PATCH "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions/$VERSION_ID/message" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Move the launch date"}'
```

### Example response

```json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## Empty the trash

`POST /v2/spaces/{space_id}/trash/purge`

Erase what is in this Space's trash: the same as [`POST /v2/entries/{id}/purge`](https://mirabase.io/developers/api/entries.md#entries-purge) for each trashed Entry you can see, so it needs `knowledge:manage` and the Space owner role, cannot be undone, and frees storage quota immediately. At most 100 Entries a call; `has_more` says to call again, and calling again is always safe. `delete_batch_id` erases only what one delete removed. List the trash first with [`GET /v2/entries?trashed=true`](https://mirabase.io/developers/api/entries.md#entries-list).

**Capability** `knowledge:manage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |

### Request body

`application/json` `DevPurgeTrashRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | Optional | Erase only what this one delete removed. Without it, everything in the Space's trash that you can see. |

### Responses

- `200` `application/json` `DevPurgeTrashReceipt`

### 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/spaces/$SPACE_ID/trash/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "purged": [
    {
      "entry_id": "<entry_id>",
      "job_id": "<job_id>"
    }
  ],
  "has_more": false
}
```
