Space 的写时复制分支,带检查点、对比和合并。
列出分支
GET/v2/spaces/{space_id}/branches
Space 下所有状态的分支,按 id 排序。受 read_root 限制的成员调用任何分支接口均返回 403 outside_read_root。需要 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 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevBranch[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}
]
}创建分支
POST/v2/spaces/{space_id}/branches
创建分支。只需要 Space 写入权限:write_mode 在合并时生效,此处不适用。同名活跃分支已存在时返回 409 branch_name_taken;Space 的活跃分支数达到上限时返回 409 branch_limit_reached。在这个 Space 设有 read_root 的成员,调用此接口和所有分支接口时都会收到 403 outside_read_root。复制的分支或检查点里路径超过 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 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreateBranchRequest from 复制另一个活跃分支,checkpoint_id 复制一个检查点。两者都不传时从主线创建。同时传两者时,checkpoint_id 必须是 from 所指分支的检查点,否则返回 404 checkpoint_not_found。
| 字段 | 类型 | 说明 |
|---|---|---|
name必填 | string | 分支的名称,1 到 255 个字符。长度 1 到 255 |
from | DevId | 要复制的活跃分支的 id。 |
checkpoint_id | DevId | 要复制的检查点的 id。 |
ttl_days | integer | 每次写入把 expires_at 推后的天数,1 到 365。不传则使用服务默认值。1 到 365 |
响应
201application/jsonDevBranch
错误状态
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/branches" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"research"}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}读取分支
GET/v2/spaces/{space_id}/branches/{branch_id}
读取一个分支。main_changed_paths 表示自 base_change_seq 以来主线发生变更的路径数。需要 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 |
branch_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
响应
200application/jsonDevBranch
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}重命名或续期分支
PATCH/v2/spaces/{space_id}/branches/{branch_id}
重命名分支,或通过设置 ttl_days 续期。至少传一个字段。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevUpdateBranchRequest 设置 ttl_days 同时续期:expires_at 更新为当前时间加上该天数。
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 新名字,1 到 255 个字符。长度 1 到 255 |
ttl_days | integer | 1 到 365。设置后同时为分支续期:expires_at 更新为当前时间加上该天数。1 到 365 |
响应
200application/jsonDevBranch
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}放弃分支
DELETE/v2/spaces/{space_id}/branches/{branch_id}
放弃分支。分支在 7 天内仍可读取,随后回收。对已放弃的分支重复调用仍返回 200;对已合并的分支调用返回 409 branch_not_active。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
响应
200application/jsonDevBranch
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}列出检查点
GET/v2/spaces/{space_id}/branches/{branch_id}/checkpoints
分支的检查点,最新的在前。需要 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 |
branch_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevCheckpoint[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"branch_id": "<branch_id>",
"name": "research",
"node_count": 1,
"created_by": "<created_by>",
"created_at": "2026-11-06T00:00:00Z"
}
]
}创建检查点
POST/v2/spaces/{space_id}/branches/{branch_id}/checkpoints
把分支自己的改动以一个名称保存下来,之后 POST .../rollback 可以回到这里。git 是一个不透明对象,按原样保存,最大 4 MiB,其中的 remote_url 不能带凭据(422)。一个分支最多有 branch_checkpoints 个检查点(见 GET /v2/limits),再多一个返回 409 checkpoint_limit_reached。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreateCheckpointRequest
| 字段 | 类型 | 说明 |
|---|---|---|
name必填 | string | 检查点的名字,1 到 255 个字符。长度 1 到 255 |
git | DevCheckpointGit |
响应
201application/jsonDevCheckpoint
错误状态
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/branches/$BRANCH_ID/checkpoints" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"research"}'响应结构示例
{
"id": "<id>",
"branch_id": "<branch_id>",
"name": "research",
"node_count": 1,
"created_by": "<created_by>",
"created_at": "2026-11-06T00:00:00Z"
}查看分支改动
GET/v2/spaces/{space_id}/branches/{branch_id}/diff
列出该分支修改过的路径,文本文件附带统一 diff。path 可将范围限定为单个文件或目录。返回顺序固定,但不按字母顺序排列。需要 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 |
branch_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
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必填 | DevBranchDiffItem[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"path": "/notes/hello.md",
"change": "added",
"kind": "dir"
}
]
}合并分支
POST/v2/spaces/{space_id}/branches/{branch_id}/merge
把分支写入主线,全部生效或全部不生效,每个路径产生一个带 message 的新版本。必须提供 Idempotency-Key。每个路径计一次写入。发生冲突时,接口返回 409 merge_conflict,冲突列在 error.conflicts。超过 1000 个路径时,接口返回 409 merge_too_large:用 paths 分批,或者带 Prefer: respond-async 作为任务执行,最多 10000 个路径(接口返回 202 和 job_id)。任务先规划全部路径,有冲突时以 merge_conflict 失败,冲突列在 result.conflicts,不写入任何内容;然后每批合并 200 个路径,所以中途出现的冲突会让任务停止,已合并的路径已从分支移除:再次合并以处理剩余路径。一个分支同时只有一个合并任务,任务排队或运行期间,对这个分支的任何合并,以及任何修改分支文件的写入(文件写入、目录操作、上传、回滚),接口都返回 409 merge_in_progress;重命名分支、创建检查点和放弃分支仍然可用,放弃分支会让任务停止。Agent 合并不属于自己的文件需要 write_mode: direct,否则接口返回 403 proposal_required;带 Prefer: handling=proposal 时,Agent 对这类文件的修改变成提案,列在 proposed_items,但删除这类文件时,接口仍返回 403 proposal_required,不写入任何内容。符号链接不进入主线,列在 skipped 里。权限位 755 保存为元数据键 mirabase.mode。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
Idempotency-Key必填 | 请求头 | DevIdempotencyKey | 此处必填,防止重复发送的合并请求执行两次。重试时请沿用同一个键。长度 1 到 512 |
Prefer | 请求头 | string | handling=proposal:proposal 模式的 Agent 修改不属于自己的文件时,改为提交提案(proposed_items)。respond-async:超过 1000 个路径的合并改为任务执行,接口返回 202 DevJobReceipt。两者可以一起用。其他偏好会被忽略。 |
请求体
application/json DevMergeRequest paths 只合并这些路径,目录连同下面的全部内容,分支保持活跃;不传时合并后分支变为 merged。on_conflict 作用于主线最新版本已不是分支起点版本的路径:abort 让整次合并失败,keep_main 跳过它们,keep_branch 覆盖主线。不做内容合并。
| 字段 | 类型 | 说明 |
|---|---|---|
message必填 | string | 1 到 1000 个字符。记为本次合并写入主线的每个版本的说明。长度 1 到 1000 |
paths | DevPath[] | 只合并这些路径,1 到 1000 个;目录会包含其下的全部内容。不传则合并整个分支。1 到 1000 项 |
on_conflict | DevMergeConflictPolicy | 对分支起点之后主线又修改过的路径的处理方式:abort、keep_main 或 keep_branch。默认 "abort" |
响应
200application/jsonDevMergeResult202application/jsonDevJobReceipt
响应头
Preference-Appliedrespond-async。Location/v2/jobs/{job_id}:轮询它,直到status变成succeeded或failed。
错误状态
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/branches/$BRANCH_ID/merge" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"message":"Move the launch date"}'响应结构示例
{
"branch_id": "<branch_id>",
"state": "active",
"merged": [
"/notes/hello.md"
],
"skipped": [
"/notes/hello.md"
],
"merged_items": [
{
"path": "/notes/hello.md",
"op": "create"
}
],
"skipped_items": [
{
"path": "/notes/hello.md",
"reason": "symlink"
}
]
}读取分支对象
GET/v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}
读取对象的字节。支持 Range 请求。分支已合并或已放弃时,在回收之前仍可读。需要 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 |
branch_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
sha256必填 | 路径 | string | 对象的小写十六进制 SHA-256(64 个字符),也是对象存储时使用的名称。 |
Range | 请求头 | string | 一个区间:bytes=0-99、bytes=100- 或 bytes=-100。响应返回 206 和对象的这一部分。 |
响应
200application/octet-streambinary206application/octet-streambinary
响应头
Content-RangeAccept-Ranges
错误状态
400 401 403 404 416 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
-H "Authorization: Bearer $MIRABASE_API_KEY"检查分支对象
HEAD/v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}
不读取字节,检查分支中是否存在该对象:存在时返回 200 并附带 Content-Length;不存在时返回 404 object_not_found。分支已合并或已放弃时,在回收之前仍可用。需要 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 |
branch_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
sha256必填 | 路径 | string | 对象的小写十六进制 SHA-256(64 个字符),也是对象存储时使用的名称。 |
响应
200无响应体
响应头
Content-Length
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl --head "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
-H "Authorization: Bearer $MIRABASE_API_KEY"写入分支对象
PUT/v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}
存储一个不透明对象,最大 16 MiB。对象用于存储 Git bundle 和 overlay:它们不是路径,不出现在 tree 和 changes 中,不合并、不解析、不索引,计入 storage_bytes。请求体的哈希与 sha256 不符时返回 422 checksum_mismatch。首次写入返回 201(created: true),写入分支已有的对象返回 200(created: false)。分支不是活跃状态返回 409 branch_not_active。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
sha256必填 | 路径 | string | 请求体的小写十六进制 SHA-256,64 个字符。对象按它存放。 |
请求体
*/* binary
响应
200application/jsonDevBranchObject201application/jsonDevBranchObject
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @object.bin响应结构示例
{
"branch_id": "<branch_id>",
"sha256": "<sha256>",
"size": 1,
"created": false
}回滚到检查点
POST/v2/spaces/{space_id}/branches/{branch_id}/rollback
回到这个分支的一个检查点。之后的检查点保留,所以回滚可以撤销。这个分支更早的 changes 游标随后返回 410 cursor_expired。需要 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_id必填 | 路径 | DevBranchRef | 分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevRollbackRequest
| 字段 | 类型 | 说明 |
|---|---|---|
checkpoint_id必填 | DevId | 要回滚到的检查点的 id。 |
响应
200application/jsonDevBranch
错误状态
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/branches/$BRANCH_ID/rollback" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"checkpoint_id":"<checkpoint_id>"}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"name": "research",
"state": "active",
"base_change_seq": 1,
"main_changed_paths": 1,
"created_by": "<created_by>",
"ttl_days": 1,
"expires_at": "2026-11-06T00:00:00Z",
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}