# Entry

按 id 访问的 Entry：内容、版本、处理、废纸篓和彻底删除。

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

## 列出 Entry

`GET /v2/entries`

调用方可见的 Entry，可用 `space_id`（也接受 `default` 或 `ext:<external_id>`）限定到一个 Space。记忆和 Agent 档案不在此列出。按 id 倒序排列，翻页期间次序不变。`trashed=true` 改为列出废纸篓中已删除且尚可恢复的 Entry，每条带 `trash`（删除时间及文件原路径）。`q` 和 `state` 可进一步筛选这两种列表。已彻底删除的 Entry 不在任一列表中。设有 `read_root` 的成员看不到废纸篓中的 Entry。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |
| `space_id` | 查询 | `DevSpaceRef` | 可选 | 只保留该 Space 的 Entry。可传 Space id、`default` 或 `ext:<external_id>`，与路径参数中的含义相同。默认 Space，和路径里的含义相同。 长度 1 到 256 |
| `trashed` | 查询 | `boolean` | 可选 | `true` 表示列出废纸篓，而不是现有的 Entry。 |
| `metadata` | 查询 | `string` | 可选 | 只保留元数据里有这些值的 Entry：一个 JSON 对象，做 URL 编码，例如 `{"status":"final"}`。每个键都要精确相等；1 到 8 个键。键对应的值为列表时，给定值须为其中的一项。 |
| `q` | 查询 | `string` | 可选 | 只保留标题或文件路径包含该文本的 Entry，不区分大小写：1 到 200 个字符，按字面匹配，用于浏览而非检索。要按语义查找 Entry，请调用 `search`。 长度 1 到 200 |
| `state` | 查询 | `DevKnowledgeState` | 可选 | 只保留 `knowledge.state` 为该值的 Entry，例如用 `failed` 列出已放弃处理的 Entry。 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevEntry[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

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

### 响应结构示例

```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"
        ]
      }
    }
  ]
}
```

## 读取 Entry

`GET /v2/entries/{entry_id}`

读取一个 Entry：有路径时包含 `file`（路径、大小、媒体类型和 ETag），以及 `latest_version_id`、`metadata` 和 `occurred_at`。需要 `knowledge:read`。Entry 不存在或调用方不可见时返回 404 `not_found`。

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

### 参数

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

### 响应

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

### 错误状态

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

### 响应结构示例

```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"
    ]
  }
}
```

## 修改 Entry

`PATCH /v2/entries/{entry_id}`

修改 Entry 的 `title`、`metadata`、`metadata_patch`、`memory_exclude` 或 `occurred_at`，至少传入一项。新的 `title` 会写入新版本，其余字段不会。文件的标题即文件名，重命名或移动请使用 `tree/operations`。需要 `knowledge:write`。

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

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

### 参数

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

### 请求体

`application/json` `DevUpdateEntryRequest` 修改标题会产生新版本：标题会纳入索引，而版本不可变。标题相同时不执行任何操作。文件的标题即文件名，因此对文件传 `title` 返回 422，请用 `tree/operations` 重命名。至少传一个字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | 可选 | 新标题，1 到 512 个字符。不适用于文件：文件请用 `tree/operations` 改名。 长度 1 到 512 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据：需传入所有要保留的键，传 `{}` 清空。不会产生新版本。对任何 Entry 都有效，文件也包括在内。Entry 重新索引后过滤即可看到变化，通常在几秒内。 |
| `metadata_patch` | `object` | 可选 | 按键修改元数据，而不是整体替换：带值的键被设置，值为 `null` 的键被删除，没提到的键保持不变。两个调用方各改不同的键不会互相覆盖。不能与 `metadata` 同时传入。合并后的结果仍然最多 32 个值。 |
| `memory_exclude` | `boolean` | 可选 | 设为 `true` 时停用从该 Entry 提炼的事实，并停止提炼；搜索和读取不受影响。设为 `false` 时重新提炼，已遗忘或更正的事实不会恢复。 |
| `occurred_at` | `string (date-time) \| null` | 可选 | 来源本身发生的时间。传入 `null` 将其清空，检索的时间过滤改回按 Entry 的写入时间计算。不会产生新版本；Entry 重新索引后过滤条件即可反映该变更，通常在几秒内完成。已提炼出的记忆保留其原有的时间。 |

### 响应

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

### 错误状态

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

### 响应结构示例

```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"
    ]
  }
}
```

## 将 Entry 移入废纸篓

`DELETE /v2/entries/{entry_id}`

把 Entry 移入废纸篓。需要 `knowledge:write` 和至少 `editor` 角色，与 `DELETE files` 相同；Entry 是文件时，它的路径一同移入废纸篓。用 `restore` 恢复。第二次删除返回 404 `not_found`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |

### 响应

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

### 错误状态

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

### 响应结构示例

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

## 读取 Entry 内容

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

按 id 读取与 `GET files` 相同的视图：`view=raw`（默认）返回原始字节，`meta` 返回 Entry，其余为内容视图。从网址导入的 Entry 没有原始字节：`view=raw` 返回 422 `view_not_available`，请改用 `view=text`。`view=raw` 时 `Range`、`If-Range` 和 `If-None-Match` 的行为与 `GET files` 相同。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `view` | 查询 | `DevFileView` | 可选 | 返回内容的哪种形式：`raw`（默认）返回字节，`meta` 返回 Entry，`text`、`table` 或 `recognized` 返回处理后的视图。 |
| `version` | 查询 | `DevId` | 可选 | 这个 Entry 某个版本的 id，读取该版本而不是最新版本。`view=meta` 不支持此参数（返回 422）。 长度 1 到 256 |
| `Range` | 请求头 | `string` | 可选 | 一个区间：`bytes=0-99`、`bytes=100-` 或 `bytes=-100`。仅对 `view=raw` 生效，其他视图忽略它。 |
| `If-Range` | 请求头 | `string` | 可选 | 一个 `ETag`。若内容已变更，则返回完整的新内容（200），而非部分区间（206）。 |
| `If-None-Match` | 请求头 | `string` | 可选 | 已持有的 `ETag`。`view=raw` 时，若字节未变则返回 304，不含响应体。 |

### 响应

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

### 响应头

- `ETag`
- `Mirabase-Entry-Id`
- `Mirabase-Version-Id`
- `Mirabase-Knowledge-State`
- `Last-Modified` 内容最后一次变更的时间，HTTP 日期格式。仅在返回最新版本时包含。
- `Content-Range`
- `Accept-Ranges`

### 错误状态

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

### 响应结构示例

```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"
    ]
  }
}
```

## 获取 Entry 下载地址

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

获取 `version`（默认最新版本）原始字节的签名下载地址，有效期为 `expires_in` 秒（60 到 300，默认 300）。检查规则与 `view=raw` 相同；从网址导入的 Entry 返回 422 `view_not_available`。签发地址前会记录审计日志。原件保存在服务器上而非对象存储中时返回 409 `content_url_unavailable`，请改用 `view=raw`。503 `original_unavailable` 表示暂时无法签发地址，请稍后重试。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `version` | 查询 | `DevId` | 可选 | 要签发地址的版本的 id。默认最新版本。 长度 1 到 256 |
| `expires_in` | 查询 | `integer` | 可选 | 地址的有效时长，单位为秒：60 到 300，默认 300。 60 到 300，默认 300 |

### 响应

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

### 错误状态

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

### 响应结构示例

```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>"
}
```

## 列出副本（即将上线）

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

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

即将上线：从该 Entry 复制产生且调用方可见的 Entry，按时间倒序排列。

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevEntryCopy[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

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

### 响应结构示例

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

## 比较版本

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

比较这个 Entry 的两个版本，`to` 默认最新版本。版本不存在或你不可见时返回 404 `not_found`。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `from` | 查询 | `DevId` | 必填 | 作为比较起点的版本的 id。 长度 1 到 256 |
| `to` | 查询 | `DevId` | 可选 | 作为比较终点的版本的 id。默认最新版本。 长度 1 到 256 |

### 响应

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

### 错误状态

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

### 响应结构示例

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

## 查看来源

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

返回该 Entry 的起源（新建、复制或从分支合并）以及各个版本的产生方式，最新的在前。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

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

### 错误状态

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

### 响应结构示例

```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"
    }
  ]
}
```

## 读取处理状态

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

返回 Entry 最新版本的处理进度：`status`、`knowledge_state`、当前的 `stage` 及 `progress`，等待期间还会返回 `queue`；失败时返回 `error`。`stage` 为 `enriching` 或 `ready` 后，搜索即可找到该版本。写入返回 202 后可轮询此接口，或在写入时发送 `Prefer: wait`。同时处理大量文件时，请轮询 [`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing)。失败的版本可用 `POST .../reprocess` 重试。需要 `knowledge:read`。

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

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

### 参数

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

### 响应

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

### 错误状态

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

### 响应结构示例

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

## 彻底删除 Entry

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

彻底删除 Entry（无论在用还是已在废纸篓中），连同其全部版本和路径，不可撤销。需要 `knowledge:manage` 和 Space 所有者身份。存储配额立即返还，彻底删除由任务完成。

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

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

### 参数

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

### 响应

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

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

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

### 响应结构示例

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

## 重新处理 Entry

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

最新版本失败时重试，否则重新处理。已有处理在进行时返回 409 `job_in_flight` 并附带 `job_id`。需要 `knowledge:write`。

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

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

### 参数

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

### 响应

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

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

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

### 响应结构示例

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

## 恢复 Entry

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

恢复废纸篓里的 Entry 及其路径。路径被占用时返回 409 `path_conflict`，不会自动重命名。已彻底删除的 Entry 返回 409。不在废纸篓的 Entry 原样返回。需要 `knowledge:write`。

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

指南：[连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md#tools)

### 参数

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

### 响应

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

### 错误状态

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

### 响应结构示例

```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"
    ]
  }
}
```

## 回滚到旧版本

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

把旧版本的内容写为新版本。不带 `If-Match` 时后写覆盖。回滚到最新版本时不执行任何操作。响应带新版本的 `ETag`，和写文件时一样。需要 `knowledge:write`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |

### 请求体

`application/json` `DevRevertRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `version_id` | `DevId` | 必填 | 要回滚到的版本的 id；它的内容成为新的最新版本。 |

### 响应

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

### 响应头

- `ETag` 刚写入内容的 `ETag`：下次写入时可传入 `If-Match`，无需重新读取文件。

### 错误状态

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

### 响应结构示例

```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 /v2/entries/{entry_id}/versions`

列出 Entry 的版本，最新的在前。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `entry_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevVersion[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

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

### 响应结构示例

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

## 读取版本

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

读取 Entry 的一个版本。版本内容永不改变；处理过程中它的 `status` 会变。版本不存在、属于另一个 Entry 或调用方不可见时返回 404 `not_found`。需要 `knowledge:read`。

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

### 参数

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

### 响应

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

### 错误状态

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

### 响应结构示例

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

## 修改版本说明

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

替换某个版本的说明，最多 120 个字符。说明是版本中唯一可以由你修改的部分。仅限 Space 所有者操作。需要 `knowledge:write`。

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

### 参数

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

### 请求体

`application/json` `DevUpdateVersionMessageRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message` | `string` | 必填 | 版本的新说明，最多 120 个字符。 最长 120 |

### 响应

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

### 错误状态

`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 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"}'
```

### 响应结构示例

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

## 清空废纸篓

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

清空该 Space 的废纸篓：相当于对废纸篓中每个可见的 Entry 执行 [`POST /v2/entries/{id}/purge`](https://mirabase.io/zh/developers/api/entries.md#entries-purge)，因此需要 `knowledge:manage` 和 Space 所有者身份，不可撤销，存储配额立即返还。单次调用最多处理 100 个 Entry；`has_more` 表示仍需继续调用，重复调用始终安全。传入 `delete_batch_id` 时仅清除该次删除移入废纸篓的 Entry。可先调用 [`GET /v2/entries?trashed=true`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 查看废纸篓中的内容。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |

### 请求体

`application/json` `DevPurgeTrashRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | 可选 | 仅彻底删除该次删除操作移除的 Entry。不传则彻底删除当前 Space 废纸篓中你可见的全部内容。 |

### 响应

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

### 错误状态

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

### 响应结构示例

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