Export and import
MarkdownExport a Space's files as an archive, and import an archive into a Space.
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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
job_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
expires_in | Query | integer | How long the URL stays valid, in seconds: 60 to 300, 300 by default.60..300, default: 300 |
Responses
200application/jsonDevArchiveUrl
Error statuses
400 401 403 404 409 410 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID/content-url" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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 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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | 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 | Description |
|---|---|---|
snapshot | DevSnapshotRef | 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 | Only this directory (or file) and what is under it. |
format | tar | The only format. |
Responses
202application/jsonDevJobReceipt
Response headers
Location/v2/jobs/{job_id}: poll it untilstatusissucceededorfailed.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
{
"job_id": "<job_id>"
}Fork a SpaceComing soon
POST/v2/spaces/{space_id}/forks
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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | 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 | Description |
|---|---|---|
nameRequired | string | The new Space's name. |
snapshot | DevSnapshotRef | Fork the files as a snapshot pinned them. Without it, the live tree. |
Responses
202application/jsonDevJobReceipt
Response headers
Location/v2/jobs/{job_id}: poll it untilstatusissucceededorfailed.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
{
"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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | 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 | Description |
|---|---|---|
source_entry_idRequired | DevId | 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 | The directory to import into, created as needed. Default /. |
on_conflict | DevImportConflict | What to do when a file is already at a member's path: skip (the default) or overwrite.default: "skip" |
Responses
202application/jsonDevJobReceipt
Response headers
Location/v2/jobs/{job_id}: poll it untilstatusissucceededorfailed.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
{
"job_id": "<job_id>"
}