整个 Space 在某一时刻的只读视图。
读取快照
GET/v2/snapshots/{snapshot_id}
读取单个快照的记录。如需读取其中的文件,请向 tree、files 和 files/content-url 传入 snapshot=<id>。需要 knowledge:read。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
snapshot_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
响应
200application/jsonDevSnapshot
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/snapshots/$SNAPSHOT_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 -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必填 | 路径 | 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必填 | DevSnapshot[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/snapshots" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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 DevCreateSnapshotRequest
| 字段 | 类型 | 说明 |
|---|---|---|
name必填 | string | 1 到 255 字节,在 Space 内唯一,不含控制字符,不以 snp_ 开头。长度 1 到 255 |
响应
201application/jsonDevSnapshot
错误状态
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/snapshots" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"research"}'响应结构示例
{
"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"
}