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

Space 的写时复制分支,带检查点、对比和合并。

列出分支

GET/v2/spaces/{space_id}/branches

Space 下所有状态的分支,按 id 排序。受 read_root 限制的成员调用任何分支接口均返回 403 outside_read_root。需要 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
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevBranch[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace 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请求头DevIdempotencyKeyIdempotency-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
fromDevId要复制的活跃分支的 id。
checkpoint_idDevId要复制的检查点的 id。
ttl_daysinteger每次写入把 expires_at 推后的天数,1 到 365。不传则使用服务默认值。1 到 365

响应

错误状态

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/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。

响应

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevUpdateBranchRequest 设置 ttl_days 同时续期:expires_at 更新为当前时间加上该天数。

字段类型说明
namestring新名字,1 到 255 个字符。长度 1 到 255
ttl_daysinteger1 到 365。设置后同时为分支续期:expires_at 更新为当前时间加上该天数。1 到 365

响应

错误状态

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

请求示例

curl
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 '{}'

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。

响应

错误状态

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

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevCheckpoint[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateCheckpointRequest

字段类型说明
name必填string检查点的名字,1 到 255 个字符。长度 1 到 255
gitDevCheckpointGit

响应

错误状态

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/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
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必填DevBranchDiffItem[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
Idempotency-Key必填请求头DevIdempotencyKey此处必填,防止重复发送的合并请求执行两次。重试时请沿用同一个键。长度 1 到 512
Prefer请求头stringhandling=proposal:proposal 模式的 Agent 修改不属于自己的文件时,改为提交提案(proposed_items)。respond-async:超过 1000 个路径的合并改为任务执行,接口返回 202 DevJobReceipt。两者可以一起用。其他偏好会被忽略。

请求体

application/json DevMergeRequest paths 只合并这些路径,目录连同下面的全部内容,分支保持活跃;不传时合并后分支变为 merged。on_conflict 作用于主线最新版本已不是分支起点版本的路径:abort 让整次合并失败,keep_main 跳过它们,keep_branch 覆盖主线。不做内容合并。

字段类型说明
message必填string1 到 1000 个字符。记为本次合并写入主线的每个版本的说明。长度 1 到 1000
pathsDevPath[]只合并这些路径,1 到 1000 个;目录会包含其下的全部内容。不传则合并整个分支。1 到 1000 项
on_conflictDevMergeConflictPolicy对分支起点之后主线又修改过的路径的处理方式:abort、keep_main 或 keep_branch。默认 "abort"

响应

响应头

  • Preference-Applied respond-async。
  • Location /v2/jobs/{job_id}:轮询它,直到 status 变成 succeeded 或 failed。

错误状态

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

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
sha256必填路径string对象的小写十六进制 SHA-256(64 个字符),也是对象存储时使用的名称。
Range请求头string一个区间:bytes=0-99、bytes=100- 或 bytes=-100。响应返回 206 和对象的这一部分。

响应

  • 200 application/octet-stream binary
  • 206 application/octet-stream binary

响应头

  • Content-Range
  • Accept-Ranges

错误状态

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

请求示例

curl
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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
sha256必填路径string对象的小写十六进制 SHA-256(64 个字符),也是对象存储时使用的名称。

响应

  • 200 无响应体

响应头

  • Content-Length

错误状态

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

请求示例

curl
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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
sha256必填路径string请求体的小写十六进制 SHA-256,64 个字符。对象按它存放。

请求体

*/* binary

响应

错误状态

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

请求示例

curl
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

响应结构示例

json
{
  "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必填路径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_id必填路径DevBranchRef分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevRollbackRequest

字段类型说明
checkpoint_id必填DevId要回滚到的检查点的 id。

响应

错误状态

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/branches/$BRANCH_ID/rollback" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checkpoint_id":"<checkpoint_id>"}'

响应结构示例

json
{
  "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"
}