# 导出与导入

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

API 参考。Base URL：`https://api.mirabase.dev`

## 获取导出归档地址

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

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

**需要的能力** `knowledge:read`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#export)

### 参数

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

### 响应

- `200` `application/json` `DevArchiveUrl`

### 错误状态

`400` `401` `403` `404` `409` `410` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`](https://mirabase.io/zh/developers/api/transfers.md#transfers-archiveurl) 下载；彻底删除这个 Space 里的任何文件会让它的导出不可用（410 `artifact_expired`，正在运行的任务以 `export_invalidated` 失败），设置或修改发起导出的成员的 `read_root` 也一样。请求体可以不传：这时导出整个 Space，与 `{}` 相同。

**需要的能力** `knowledge:read`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#export)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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` | 可选 | 唯一支持的格式。 |

### 响应

- `202` `application/json` `DevJobReceipt`

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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，再将归档导入其中。

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#export)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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` | 可选 | 按快照固定的文件复刻。不带时用实时目录树。 |

### 响应

- `202` `application/json` `DevJobReceipt`

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#export)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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" |

### 响应

- `202` `application/json` `DevJobReceipt`

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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>"
}
```
