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

整个 Space 在某一时刻的只读视图。

读取快照

GET/v2/snapshots/{snapshot_id}

读取单个快照的记录。如需读取其中的文件,请向 tree、files 和 files/content-url 传入 snapshot=<id>。需要 knowledge:read。

需要的能力 knowledge:read

参数

名称位置类型说明
snapshot_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}

删除快照

DELETE/v2/snapshots/{snapshot_id}

删除快照。仅快照创建者或 Space 所有者可删除,需要 knowledge:write。快照固定的版本仍会保留。第二次删除返回 404 snapshot_not_found。

需要的能力 knowledge:write

参数

名称位置类型说明
snapshot_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

  • 204 无响应体

错误状态

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

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

列出快照

GET/v2/spaces/{space_id}/snapshots

列出 Space 的快照,最新的在前。需要 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必填DevSnapshot[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

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

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "name": "research",
      "file_count": 1,
      "changes_cursor": "<cursor>",
      "created_by_principal_id": "<created_by_principal_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

创建快照

POST/v2/spaces/{space_id}/snapshots

为整个 Space 创建快照。需要 knowledge:write 和 editor 角色;由于不修改任何内容,Agent 的 write_mode 不适用。计一次写入,不计字节。一个 Space 最多保留 100 个快照(超出返回 409 too_many_snapshots),一个快照最多包含 10000 个文件(超出返回 409 snapshot_too_large,且不保存任何内容);名称已被占用时返回 409 snapshot_name_taken。Space 繁忙时返回 409 space_busy。

需要的能力 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 DevCreateSnapshotRequest

字段类型说明
name必填string1 到 255 字节,在 Space 内唯一,不含控制字符,不以 snp_ 开头。长度 1 到 255

响应

错误状态

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

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}