跳到主要内容
开发者文档
文档目录

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

读取文件

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

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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 和处理后的视图在版本不变时也会变化。

响应

响应头

  • 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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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),写入会超出时返回 409 branch_too_large。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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查询stringEntry 的元数据,为经 URL 编码的 JSON 对象,例如 {"device":"cam-01"},结构与限制同请求体中的 metadata。该值整体替换 Entry 的元数据;不传则保留现有元数据。仅适用于主线:带 branch 时返回 422。
memory_exclude查询booleantrue 让这个文件不参与记忆提炼;false 重新提炼。和 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关。只有传了才会改。只对主线:带 branch 返回 422。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
If-Match请求头string传入一个 ETag(带引号的版本 id):不是最新版本时返回 412。或传入 *:文件或 Entry 不存在时返回 412。不传时后写覆盖。
Prefer请求头stringwait=N(最大 10):最多等待 N 秒,直至该版本处理完成。写入已提交,等待超时仅表示 knowledge.state 尚未达到 indexed。在 files 写入上,handling=proposal 把本该返回 403 proposal_required 的写入变成提案(202 DevProposalReceipt);其他情况下不起作用。其他偏好会被忽略。
If-None-Match请求头string* 表示只创建;文件已存在时返回 412 precondition_failed。

请求体

*/* binary

响应

响应头

  • 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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
If-Match请求头string传入一个 ETag(带引号的版本 id):不是最新版本时返回 412。或传入 *:文件或 Entry 不存在时返回 412。不传时后写覆盖。
Prefer请求头stringwait=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 项

响应

响应头

  • 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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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)

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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。不传时后写覆盖。

响应

错误状态

400 401 403 404 405 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace 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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
Prefer请求头stringhandling=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_idstring这些改动出自你的哪段对话,与 PUT files?session_id= 相同:它会记录在每条 put 创建的版本上,可在 lineage 中查看。仅适用于主线:带 branch 时返回 422。长度 1 到 256

响应

响应头

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

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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,也可以取 snapshot 固定的版本。branch 返回 422:分支上的字节暂时没有直接下载地址。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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

响应

错误状态

400 401 403 404 409 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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。分支有自己的 diff,所以这里带 branch 返回 422。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 64 层、4096 字节,单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较,并保留写入时的拼写。不允许 .、..、控制字符、反斜杠和首尾空白。/.mirabase/ 是保留路径,/.mirabase/skills/<name>/... 除外。路径超出这些限制时返回 422 path_too_long。长度 1 到 4096
from必填查询DevId作为比较起点的版本的 id。长度 1 到 256
to查询DevId作为比较终点的版本的 id。默认最新版本。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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:将某个旧版本的内容写为新版本。不带 If-Match 时后写覆盖;回滚到最新版本不会创建新版本。响应带新的 ETag。需要 knowledge:write。

需要的能力 knowledge:write

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 64 层、4096 字节,单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较,并保留写入时的拼写。不允许 .、..、控制字符、反斜杠和首尾空白。/.mirabase/ 是保留路径,/.mirabase/skills/<name>/... 除外。路径超出这些限制时返回 422 path_too_long。长度 1 到 4096
Idempotency-Key请求头DevIdempotencyKeyIdempotency-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;它的内容成为新的最新版本。

响应

响应头

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

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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,按从新到旧列出版本。仅适用于主线:分支没有版本,带 branch 时返回 422。需要 knowledge:read。

需要的能力 knowledge:read

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
path必填查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 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
字段类型说明
data必填DevVersion[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

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