# Export and import

Export a Space's files as an archive, and import an archive into a Space.

API reference. Base URL: `https://api.mirabase.dev`

## Get an export's archive URL

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

A signed URL for an export's archive. Only whoever started the export and the Space owner can get it. An export still running returns 409 `artifact_not_ready`; one that failed, expired after 7 days, or was invalidated by a purge returns 410 `artifact_expired`. Any other job returns 404. Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#export)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `job_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `expires_in` | Query | `integer` | Optional | How long the URL stays valid, in seconds: 60 to 300, 300 by default. 60..300, default: 300 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `409` `410` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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

## Export a Space

`POST /v2/spaces/{space_id}/exports`

Export the Space's files as a tar archive, always as a job: returns 202 with `job_id` and `Location`. Needs `knowledge:read` and a Space you can see; a member with a `read_root` exports only what is under it, and a `path` outside it returns 404. The file list is fixed when the job starts, so the archive is consistent at that moment; with `snapshot`, at the snapshot's. The archive holds `manifest.json` (`format: "mirabase-export/1"`, each file's `path`, `entry_id`, `version_id`, `size_bytes`, `media_type`, `sha256`), then each file at `files/<path>`. Only files are exported: content without a path, memories, and version history are not. An export over 10,000 files or the deployment's byte limit returns 409 `export_too_large` (export one `path` at a time). A Space runs at most 4 exports at a time, counted apart from jobs that change the tree (429 `too_many_jobs`). Download with [`GET /v2/jobs/{job_id}/content-url`](https://mirabase.io/developers/api/transfers.md#transfers-archiveurl) for 7 days; purging any file in the Space makes its exports unavailable (410 `artifact_expired`, or the running job fails with `export_invalidated`), and so does setting or changing the `read_root` of the member who started the export. The body can be left out: that exports the whole Space, the same as `{}`.

**Capability** `knowledge:read`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#export)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Request body

`application/json` `DevCreateExportRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot` | `DevSnapshotRef` | Optional | A snapshot id or name: export the files as they were then. Without it, the live tree at the moment the job starts. |
| `path` | `DevPath` | Optional | Only this directory (or file) and what is under it. |
| `format` | `tar` | Optional | The only format. |

### Responses

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

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```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 '{}'
```

### Example response

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

## Fork a Space (Coming soon)

`POST /v2/spaces/{space_id}/forks`

> This is not live yet. Endpoints and fields may change.

Planned: copy this Space into a new Space you own. Until then, take a snapshot, export it with `snapshot`, create a Space, and import the archive there.

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#export)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Request body

`application/json` `DevCreateForkRequest` A fork of a Space into a new Space you own. Planned.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The new Space's name. |
| `snapshot` | `DevSnapshotRef` | Optional | Fork the files as a snapshot pinned them. Without it, the live tree. |

### Responses

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

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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

## Import an archive

`POST /v2/spaces/{space_id}/imports`

Import a tar or gzip-compressed tar archive into this Space, always as a job: returns 202 with `job_id` and `Location`. Needs `knowledge:write`, `knowledge:read`, editor, and a target directory inside your `write_root`. An archive exported by this API imports its `files/` members under `path` with their recorded media types from `manifest.json`, so export and import round-trip; any other archive imports every member under `path`, with the media type inferred from the file name. Each file is written like `PUT .../files`: the same path rules, write roots, `write_mode`, quotas, and change events, and the same bytes make no new version. A member that cannot be written (bad or reserved path, a link or special file, over 16 MiB, a conflict, an Agent in `proposal` mode changing a file it does not own) counts in `result.failed` and the job goes on; `result.failures` gives the first 100 by member index and error code, never by path. The job is not atomic: it commits 200 members at a time, and a quota running out stops it with what was already imported kept. A non-tar archive returns 422 `unsupported_archive`; an archive over the deployment's size limit or over 10,000 members returns 413 `archive_too_large`.

**Capability** `knowledge:write` `knowledge:read`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#export)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Request body

`application/json` `DevCreateImportRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source_entry_id` | `DevId` | Required | An Entry you can read whose latest version is a tar or gzip-compressed tar archive. Put the archive in any Space first with `PUT .../files` or `uploads`. The version is pinned when the job is created. |
| `path` | `DevPath` | Optional | The directory to import into, created as needed. Default `/`. |
| `on_conflict` | `DevImportConflict` | Optional | What to do when a file is already at a member's path: `skip` (the default) or `overwrite`. default: "skip" |

### Responses

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

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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