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

导出与导入

Markdown 版

把 Space 的文件导出成归档,以及把归档导入 Space。

获取导出归档地址

GET/v2/jobs/{job_id}/content-url

导出归档的签名地址。仅限发起导出的主体和 Space 所有者获取。导出仍在运行时返回 409 artifact_not_ready;导出失败、7 天后过期或被彻底删除作废时返回 410 artifact_expired。其他任务返回 404。需要 knowledge:read。

需要的能力 knowledge:read

指南:同步、快照与导出

参数

名称位置类型说明
job_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
expires_in查询integer地址的有效时长,单位为秒:60 到 300,默认 300。60 到 300,默认 300

响应

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID/content-url" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "url": "https://example.com/article",
  "method": "GET",
  "expires_at": "2026-11-06T00:00:00Z",
  "job_id": "<job_id>",
  "size_bytes": 1,
  "media_type": "<media_type>",
  "sha256": "<sha256>"
}

导出 Space

POST/v2/spaces/{space_id}/exports

把 Space 的文件导出为 tar 归档,总是作为任务执行:返回 202,带 job_id 和 Location。需要 knowledge:read,且该 Space 对你可见;设有 read_root 的成员只导出其范围内的内容,path 在范围外时返回 404。任务开始时即固定文件列表,因此归档对应那一刻的状态;指定 snapshot 时对应快照所在时刻的状态。归档里先是 manifest.json(format: "mirabase-export/1",每个文件的 path、entry_id、version_id、size_bytes、media_type、sha256),然后每个文件放在 files/<path>。只导出文件:没有路径的内容、记忆和版本历史都不导出。超过 10000 个文件或部署的字节上限返回 409 export_too_large(按 path 分次导出)。一个 Space 同时最多运行 4 个导出,与改动目录树的任务分开计数(429 too_many_jobs)。7 天内用 GET /v2/jobs/{job_id}/content-url 下载;彻底删除这个 Space 里的任何文件会让它的导出不可用(410 artifact_expired,正在运行的任务以 export_invalidated 失败),设置或修改发起导出的成员的 read_root 也一样。请求体可以不传:这时导出整个 Space,与 {} 相同。

需要的能力 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
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateExportRequest

字段类型说明
snapshotDevSnapshotRef快照 id 或名字:导出当时的文件。不带时导出任务开始那一刻的实时目录树。
pathDevPath只导出这个目录(或文件)及其下面的内容。
formattar唯一支持的格式。

响应

响应头

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

响应结构示例

json
{
  "job_id": "<job_id>"
}

复刻 Space即将上线

POST/v2/spaces/{space_id}/forks

尚未上线,接口和字段可能调整。

即将上线:把这个 Space 复制成一个你拥有的新 Space。在此之前,请先创建快照,指定 snapshot 导出,新建一个 Space,再将归档导入其中。

指南:同步、快照与导出

参数

名称位置类型说明
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 DevCreateForkRequest 把一个 Space 复刻成你拥有的新 Space。即将上线。

字段类型说明
name必填string新 Space 的名字。
snapshotDevSnapshotRef按快照固定的文件复刻。不带时用实时目录树。

响应

响应头

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

响应结构示例

json
{
  "job_id": "<job_id>"
}

导入归档

POST/v2/spaces/{space_id}/imports

把 tar 或 gzip 压缩的 tar 归档导入这个 Space,总是作为任务执行:返回 202,带 job_id 和 Location。需要 knowledge:write、knowledge:read、editor 角色,目标目录在你的 write_root 以内。本 API 导出的归档会把 files/ 下的成员连同 manifest.json 记录的媒体类型导入到 path 下,所以导出再导入能还原;其他归档的每个成员都导入到 path 下,媒体类型按文件名推断。每个文件都像 PUT .../files 一样写入:路径规则、写入根路径、write_mode、配额和变更事件都相同,同样的字节不产生新版本。无法写入的成员(路径不合法或为保留路径、链接或特殊文件、超过 16 MiB、冲突、proposal 模式的 Agent 修改不属于自己的文件)计入 result.failed,任务继续执行;result.failures 按成员序号和错误码列出前 100 项,不包含路径。任务不是原子的:每次提交 200 个成员,配额用尽时任务停止,已导入的内容保留。不是 tar 归档返回 422 unsupported_archive;超过部署的大小上限或超过 10000 个成员返回 413 archive_too_large。

需要的能力 knowledge:write 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
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateImportRequest

字段类型说明
source_entry_id必填DevId一个你可读的 Entry,其最新版本为 tar 或 gzip 压缩的 tar 归档。请先使用 PUT .../files 或 uploads 将归档上传至任意 Space。创建任务时固定该版本。
pathDevPath导入到的目录,需要时自动创建。默认 /。
on_conflictDevImportConflict成员目标路径上已有文件时的处理方式:skip(默认)或 overwrite。默认 "skip"

响应

响应头

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

响应结构示例

json
{
  "job_id": "<job_id>"
}