# 文件

按路径访问的文件：读取、写入、编辑、删除，以及它们的历史。

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

## 读取文件

`GET /v2/spaces/{space_id}/files`

`view=raw`（默认）返回字节，`meta` 返回 Entry，其余返回内容视图。`version` 读旧版本，`meta` 除外。目录返回 404，请用 `tree`。文本文件写入后立即可读 `text`；其他视图在处理完成前返回 404 `content_not_ready`。`view=raw` 时 `Range` 返回一个字节区间，状态码为 206；区间超出文件返回 416 `range_not_satisfiable`。多个区间或无法解析的 `Range` 会被忽略，返回 200 和整个文件。带 `branch` 时，分支已修改的路径从分支读取，其余从主线最新版本读取；已修改的路径支持 `raw`、`meta`（文本文件还支持 `text`），不接受 `version`。带 `snapshot` 时按快照固定的版本读取，即使文件此后已修改、移动或移入废纸篓；除 `meta` 外的视图都能用（`meta` 返回 422 `view_not_available`），响应带 `Mirabase-Snapshot-Id`。`/.mirabase/memory/MEMORY.md` 是生成的只读视图，供开始工作的 Agent 读取该 Space 的记忆。相同的记忆生成相同的字节，可用作 prompt 缓存前缀。该文件仅支持 `view=raw`，没有版本，不出现在 `tree` 中，`If-None-Match` 命中时返回 304。写入返回 405 `virtual_file`。开启了离线整理的部署上，`MEMORY.md` 分节（规则和偏好、决定和进度、事实），每行一条记忆，行尾带 `[m1]` 等引用号，末尾的 `References` 表将引用号映射到记忆 id；内容为人工写入的记忆和已确认的提炼记忆，最多 2,000 Token，`ETag` 以 `mf2.` 开头。另有一个生成文件 `/.mirabase/memory/RECENT.md`，列出这个 Space 最近 7 天写下的记忆，包括候选，最新的在前，引用号是 `[r1]`（`ETag` 前缀 `rf1.`），规则同上。两个文件均只包含对你可见的记忆，因此不同调用方可能获得不同的字节。其他部署上 `RECENT.md` 是保留路径。503 `original_unavailable` 表示存储的字节暂时无法读取，请稍后重试。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `snapshot` | 查询 | `DevSnapshotRef` | 可选 | 快照 id 或名称。路径、版本和 `read_root` 均按创建快照时的状态判断；文件当前也必须对你可见。 |
| `view` | 查询 | `DevFileView` | 可选 | 返回文件的哪种形式：`raw`（默认）返回字节，`meta` 返回 Entry，`text`、`table` 或 `recognized` 返回处理后的视图。 |
| `version` | 查询 | `DevId` | 可选 | 这个文件某个版本的 id：读这个版本，而不是最新版本。`view=meta` 不接受它（422）。 长度 1 到 256 |
| `Range` | 请求头 | `string` | 可选 | 一个区间：`bytes=0-99`、`bytes=100-` 或 `bytes=-100`。仅对 `view=raw` 生效，其他视图忽略它。 |
| `If-Range` | 请求头 | `string` | 可选 | 一个 `ETag`。文件已有新版本时返回 200 和整个文件，而不是区间。 |
| `If-None-Match` | 请求头 | `string` | 可选 | 你已持有的 `ETag`。`view=raw`（默认）时字节未变则返回 304，不带响应体。其他视图不做条件读取：`meta` 和处理后的视图在版本不变时也会变化。 |

### 响应

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

### 响应头

- `ETag`
- `Mirabase-Entry-Id`
- `Mirabase-Version-Id`
- `Mirabase-Knowledge-State`
- `Last-Modified` 内容最后一次变更的时间，HTTP 日期格式。仅在返回最新版本时包含。
- `Mirabase-Snapshot-Id` 带 `snapshot` 时：这次读取所用快照的 id。
- `Mirabase-Branch-Id` 带 `branch` 时：这次读取所经分支的 id。
- `Mirabase-Path` 带 `snapshot` 时，以及带 `branch` 且分支未修改该路径时：实际返回的文件路径（百分号编码）。
- `Mirabase-Sha256` 带 `branch` 且分支改过这个文件时：它在分支上的字节的十六进制 SHA-256。
- `Mirabase-Mode` 带 `branch` 且分支改过这个路径时：它的权限位，`644` 或 `755`。
- `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/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -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"
    ]
  }
}
```

## 读取文件响应头

`HEAD /v2/spaces/{space_id}/files`

返回最新版本、`branch` 上的文件或 `snapshot` 固定的版本的响应头，含 `Content-Type` 和 `Content-Length`，没有响应体。需要 `knowledge:read`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `snapshot` | 查询 | `DevSnapshotRef` | 可选 | 快照 id 或名称。路径、版本和 `read_root` 均按创建快照时的状态判断；文件当前也必须对你可见。 |

### 响应

- `200` 无响应体

### 响应头

- `ETag`
- `Mirabase-Entry-Id`
- `Mirabase-Version-Id`
- `Mirabase-Knowledge-State`
- `Last-Modified` 内容最后一次变更的时间，HTTP 日期格式。仅在返回最新版本时包含。
- `Mirabase-Snapshot-Id` 带 `snapshot` 时：这次读取所用快照的 id。
- `Mirabase-Branch-Id` 带 `branch` 时：这次读取所经分支的 id。
- `Mirabase-Path` 带 `snapshot` 时，以及带 `branch` 且分支未修改该路径时：实际返回的文件路径（百分号编码）。
- `Mirabase-Sha256` 带 `branch` 且分支改过这个文件时：它在分支上的字节的十六进制 SHA-256。
- `Mirabase-Mode` 带 `branch` 且分支改过这个路径时：它的权限位，`644` 或 `755`。

### 错误状态

`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 --head "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## 写入文件

`PUT /v2/spaces/{space_id}/files`

创建或替换文件，最大 16 MiB。创建返回 201，更新返回 200，两者都已提交且可读。不带 `If-Match` 时后写覆盖。字节和媒体类型均未变化时返回 200 和 `version_created: false`。Agent 修改不属于自己的文件需要 `write_mode: direct`，否则返回 403 `proposal_required`；带 `Prefer: handling=proposal` 时这次写入改为提案，返回 202 和 `Preference-Applied: handling=proposal`，审核人批准之前文件不变。`If-Match` 仍然生效，内容相同仍返回 200。有 `write_root` 的成员写范围外的路径返回 403 `outside_write_root`。Space 繁忙时返回 409 `space_busy` 并带 `Retry-After`。带 `branch` 时字节写到分支：合并之前不产生版本、不处理、不计 `writes`，响应是 `DevBranchFileWrite`。变成提案的写入不能携带 `occurred_at`、`metadata` 或 `memory_exclude`（返回 422）。同一作者在一个 Space 内最多有 100 个打开的提案，超出时返回 409 `too_many_open_proposals`。一个分支最多有 `branch_paths` 个路径（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)），写入会超出时返回 409 `branch_too_large`。需要 `knowledge:write`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `mode` | 查询 | `644 \| 755` | 可选 | 文件权限，`644` 或 `755`（可执行）。只在带 `branch` 时有效。不传时新文件是 `644`，已有文件保留原来的权限位。 |
| `session_id` | 查询 | `string` | 可选 | 本次修改来源对话的 id（1 到 256 个字符），即导入该对话时使用的 `session_id`。该值记录在本次写入创建的版本上，并在 `lineage` 中返回，便于后续读者确认并查找修改该文件的对话。仅适用于主线：带 `branch` 时返回 422。 长度 1 到 256 |
| `occurred_at` | 查询 | `string (date-time)` | 可选 | 文件内容发生的时间（例如音视频的录制时间），格式为带时区偏移的 RFC 3339，需进行 URL 编码。检索时的 `occurred_from` / `occurred_to` 按该时间过滤，返回的段落也会包含该时间。仅在传入时更新。仅适用于主线：带 `branch` 时返回 422。 |
| `metadata` | 查询 | `string` | 可选 | Entry 的元数据，为经 URL 编码的 JSON 对象，例如 `{"device":"cam-01"}`，结构与限制同请求体中的 `metadata`。该值整体替换 Entry 的元数据；不传则保留现有元数据。仅适用于主线：带 `branch` 时返回 422。 |
| `memory_exclude` | 查询 | `boolean` | 可选 | `true` 让这个文件不参与记忆提炼；`false` 重新提炼。和 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关。只有传了才会改。只对主线：带 `branch` 返回 422。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |
| `Prefer` | 请求头 | `string` | 可选 | `wait=N`（最大 10）：最多等待 N 秒，直至该版本处理完成。写入已提交，等待超时仅表示 `knowledge.state` 尚未达到 `indexed`。在 `files` 写入上，`handling=proposal` 把本该返回 403 `proposal_required` 的写入变成提案（202 `DevProposalReceipt`）；其他情况下不起作用。其他偏好会被忽略。 |
| `If-None-Match` | 请求头 | `string` | 可选 | `*` 表示只创建；文件已存在时返回 412 `precondition_failed`。 |

### 请求体

`*/*` `binary`

### 响应

- `200` `application/json` `DevFileWrite | DevBranchFileWrite`
- `201` `application/json` `DevFileWrite | DevBranchFileWrite`
- `202` `application/json` `DevProposalReceipt`

### 响应头

- `Preference-Applied` 在接受 `Prefer: wait` 的操作上，请求实际发生等待时返回 `wait=N`；未等待时不返回（例如该 Key 已有 4 个等待中的请求）。写入转为提案时返回 `handling=proposal`。
- `ETag` 刚写入内容的 `ETag`：下次写入时可传入 `If-Match`，无需重新读取文件。
- `Location` `/v2/proposals/{proposal_id}`：这次写入变成的提案可以在这里读取。

### 错误状态

`400` `401` `403` `404` `405` `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 PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @hello.md
```

### 响应结构示例

```json
{
  "entry": {
    "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"
      ]
    }
  },
  "version_id": "<version_id>",
  "version_created": false
}
```

## 修改文件文本

`PATCH /v2/spaces/{space_id}/files`

应用文本修改。`old_text` 没有匹配时返回 422 `edit_no_match`，未设 `replace_all` 而匹配多处时返回 422 `edit_ambiguous`；两者都不产生版本。`Prefer: handling=proposal` 与 `PUT` 相同：修改作用在最新版本上，把整个结果作为提案提交。需要 `knowledge:write`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `session_id` | 查询 | `string` | 可选 | 本次修改来源对话的 id（1 到 256 个字符），即导入该对话时使用的 `session_id`。该值记录在本次写入创建的版本上，并在 `lineage` 中返回，便于后续读者确认并查找修改该文件的对话。仅适用于主线：带 `branch` 时返回 422。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |
| `Prefer` | 请求头 | `string` | 可选 | `wait=N`（最大 10）：最多等待 N 秒，直至该版本处理完成。写入已提交，等待超时仅表示 `knowledge.state` 尚未达到 `indexed`。在 `files` 写入上，`handling=proposal` 把本该返回 403 `proposal_required` 的写入变成提案（202 `DevProposalReceipt`）；其他情况下不起作用。其他偏好会被忽略。 |

### 请求体

`application/json` `DevFilePatchRequest` 只支持 UTF-8 文本文件，其他返回 415 `unsupported_media_type`。超过 1 MiB 返回 413 `patch_base_too_large`，请改用 `PUT` 替换。修改按顺序应用，每条作用于上一条的结果。请求期间基线变化时重试一次，再失败返回 412 `precondition_failed`；带 `If-Match` 时不重试。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `edits` | `DevFileEdit[]` | 必填 | 1 到 100 处修改，按顺序应用。 1 到 100 项 |

### 响应

- `200` `application/json` `DevFileWrite | DevBranchFileWrite`
- `202` `application/json` `DevProposalReceipt`

### 响应头

- `Preference-Applied` 在接受 `Prefer: wait` 的操作上，请求实际发生等待时返回 `wait=N`；未等待时不返回（例如该 Key 已有 4 个等待中的请求）。写入转为提案时返回 `handling=proposal`。
- `ETag` 刚写入内容的 `ETag`：下次写入时可传入 `If-Match`，无需重新读取文件。
- `Location` `/v2/proposals/{proposal_id}`：这次写入变成的提案可以在这里读取。

### 错误状态

`400` `401` `403` `404` `405` `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/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"edits":[{"old_text":"<old_text>","new_text":"<new_text>"}]}'
```

### 响应结构示例

```json
{
  "entry": {
    "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"
      ]
    }
  },
  "version_id": "<version_id>",
  "version_created": false
}
```

## 删除文件

`DELETE /v2/spaces/{space_id}/files`

把文件移入废纸篓：有 `knowledge:write` 和 editor 即可。用 `tree/operations` 中的 `restore` 恢复。第二次删除返回 404；重试时若需区分两者，请使用带 `Idempotency-Key` 的 `files/batch`。目标是目录时返回 404，请用 `tree/operations`。带 `branch` 时只在该分支上隐藏文件，主线不变。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |

### 响应

- `200` `application/json` `DevFileDeletion | DevBranchFileDeletion`

### 错误状态

`400` `401` `403` `404` `405` `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/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 批量写入和删除

`POST /v2/spaces/{space_id}/files/batch`

在一个请求里写入和删除多个文本文件：1 到 50 个条目，每条 `put` 最多 64 KiB 的 UTF-8 文本，总量最多 1 MiB（超出返回 413 `payload_too_large`）。每个条目按顺序各自提交，响应里每个条目有一条结果。`Prefer: handling=proposal` 作用于每条 `put`：变成提案的条目状态是 202，带 `proposal`。删除永远不会变成提案。需要 `knowledge:write`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |
| `Prefer` | 请求头 | `string` | 可选 | `handling=proposal`：将本会返回 403 `proposal_required` 的写入（即 `proposal` 模式的 Agent 修改不属于自己的文件）转为创建提案；其他情况下不起作用。其他偏好会被忽略。 |

### 请求体

`application/json` `DevFileBatchRequest` 最多 50 个条目，总量 1 MiB。每个条目按顺序在各自的事务中提交。一个条目失败不影响其余条目：服务返回 200，每条结果有自己的 `status`。带 `Idempotency-Key` 再发一次可完成请求：已提交的条目重放，其余的继续执行。Entry 之后被彻底删除的条目重放为 410 `gone`，`path` 为 `/`：写入已发生，回执随 Entry 一起彻底删除。请按位置对应结果和条目。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `items` | `DevFileBatchItem[]` | 必填 | 1 到 50 个写入和删除，按顺序执行。 1 到 50 项 |
| `session_id` | `string` | 可选 | 这些改动出自你的哪段对话，与 `PUT files?session_id=` 相同：它会记录在每条 `put` 创建的版本上，可在 `lineage` 中查看。仅适用于主线：带 `branch` 时返回 422。 长度 1 到 256 |

### 响应

- `200` `application/json` `DevFileBatchResponse`

### 响应头

- `Preference-Applied` 在接受 `Prefer: wait` 的操作上，请求实际发生等待时返回 `wait=N`；未等待时不返回（例如该 Key 已有 4 个等待中的请求）。写入转为提案时返回 `handling=proposal`。

### 错误状态

`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/files/batch" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"op":"put","path":"/notes/hello.md","content":"The launch moved to March 14.\n"}]}'
```

### 响应结构示例

```json
{
  "data": [
    {
      "path": "/notes/hello.md",
      "status": 1
    }
  ]
}
```

## 获取文件下载地址

`GET /v2/spaces/{space_id}/files/content-url`

按 `path` 找到文件后等同 [`GET /v2/entries/{entry_id}/content-url`](https://mirabase.io/zh/developers/api/entries.md#entries-contenturl)，也可以取 `snapshot` 固定的版本。`branch` 返回 422：分支上的字节暂时没有直接下载地址。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `version` | 查询 | `DevId` | 可选 | 要签发地址的版本的 id。默认最新版本。 长度 1 到 256 |
| `snapshot` | 查询 | `DevSnapshotRef` | 可选 | 快照 id 或名称。路径、版本和 `read_root` 均按创建快照时的状态判断；文件当前也必须对你可见。 |
| `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/spaces/$SPACE_ID/files/content-url?path=/notes/hello.md" \
  -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/spaces/{space_id}/files/diff`

按 `path` 找到文件后等同 [`GET /v2/entries/{entry_id}/diff`](https://mirabase.io/zh/developers/api/entries.md#entries-diff)。分支有自己的 `diff`，所以这里带 `branch` 返回 422。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `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/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&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/spaces/{space_id}/files/lineage`

按 `path` 找到文件后等同 [`GET /v2/entries/{entry_id}/lineage`](https://mirabase.io/zh/developers/api/entries.md#entries-lineage)。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `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/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
  -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"
    }
  ]
}
```

## 按路径回滚

`POST /v2/spaces/{space_id}/files/revert`

按 `path` 找到文件后等同 [`POST /v2/entries/{entry_id}/revert`](https://mirabase.io/zh/developers/api/entries.md#entries-revert)：将某个旧版本的内容写为新版本。不带 `If-Match` 时后写覆盖；回滚到最新版本不会创建新版本。响应带新的 `ETag`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `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/spaces/$SPACE_ID/files/revert?path=/notes/hello.md" \
  -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/spaces/{space_id}/files/versions`

按 `path` 找到文件后等同 [`GET /v2/entries/{entry_id}/versions`](https://mirabase.io/zh/developers/api/entries.md#entries-listversions)，按从新到旧列出版本。仅适用于主线：分支没有版本，带 `branch` 时返回 422。需要 `knowledge:read`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 必填 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `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/spaces/$SPACE_ID/files/versions?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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