导出与导入
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 |
响应
200application/jsonDevArchiveUrl
错误状态
400 401 403 404 409 410 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID/content-url" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | 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 DevCreateExportRequest
| 字段 | 类型 | 说明 |
|---|---|---|
snapshot | DevSnapshotRef | 快照 id 或名字:导出当时的文件。不带时导出任务开始那一刻的实时目录树。 |
path | DevPath | 只导出这个目录(或文件)及其下面的内容。 |
format | tar | 唯一支持的格式。 |
响应
202application/jsonDevJobReceipt
响应头
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/exports" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"job_id": "<job_id>"
}复刻 Space即将上线
POST/v2/spaces/{space_id}/forks
即将上线:把这个 Space 复制成一个你拥有的新 Space。在此之前,请先创建快照,指定 snapshot 导出,新建一个 Space,再将归档导入其中。
指南:同步、快照与导出
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
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 DevCreateForkRequest 把一个 Space 复刻成你拥有的新 Space。即将上线。
| 字段 | 类型 | 说明 |
|---|---|---|
name必填 | string | 新 Space 的名字。 |
snapshot | DevSnapshotRef | 按快照固定的文件复刻。不带时用实时目录树。 |
响应
202application/jsonDevJobReceipt
响应头
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/forks" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"research"}'响应结构示例
{
"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必填 | 路径 | 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 DevCreateImportRequest
| 字段 | 类型 | 说明 |
|---|---|---|
source_entry_id必填 | DevId | 一个你可读的 Entry,其最新版本为 tar 或 gzip 压缩的 tar 归档。请先使用 PUT .../files 或 uploads 将归档上传至任意 Space。创建任务时固定该版本。 |
path | DevPath | 导入到的目录,需要时自动创建。默认 /。 |
on_conflict | DevImportConflict | 成员目标路径上已有文件时的处理方式:skip(默认)或 overwrite。默认 "skip" |
响应
202application/jsonDevJobReceipt
响应头
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/imports" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source_entry_id":"<source_entry_id>"}'响应结构示例
{
"job_id": "<job_id>"
}