按路径访问的文件:读取、写入、编辑、删除,以及它们的历史。
读取文件
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必填 | 路径 | 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/jsonDevEntry | DevEntryContent | DevBranchFileMeta | DevBranchFileText | DevEntry | DevEntryContent206*/*binary
响应头
ETagMirabase-Entry-IdMirabase-Version-IdMirabase-Knowledge-StateLast-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-RangeAccept-Ranges
错误状态
400 401 403 404 416 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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无响应体
响应头
ETagMirabase-Entry-IdMirabase-Version-IdMirabase-Knowledge-StateLast-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 --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必填 | 路径 | 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} 的 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
响应
200application/jsonDevFileWrite | DevBranchFileWrite201application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
响应头
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 -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响应结构示例
{
"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必填 | 路径 | 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 项 |
响应
200application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
响应头
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 -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>"}]}'响应结构示例
{
"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
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
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。不传时后写覆盖。 |
响应
200application/jsonDevFileDeletion | DevBranchFileDeletion
错误状态
400 401 403 404 405 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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 |
响应
200application/jsonDevFileBatchResponse
响应头
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 -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"}]}'响应结构示例
{
"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必填 | 路径 | 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 |
响应
200application/jsonDevContentUrl
错误状态
400 401 403 404 409 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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 |
响应
200application/jsonDevVersionDiff
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=<from>" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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 |
响应
200application/jsonDevLineage
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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;它的内容成为新的最新版本。 |
响应
200application/jsonDevEntry
响应头
ETag刚写入内容的ETag:下次写入时可传入If-Match,无需重新读取文件。
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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>"}'响应结构示例
{
"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必填 | 路径 | 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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevVersion[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/versions?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"entry_id": "<entry_id>",
"status": "accepted",
"created_at": "2026-11-06T00:00:00Z"
}
]
}