Skip to content
Developer docs
Docs menu

Snapshots

Markdown

Read-only, point-in-time views of a whole Space.

Read a snapshot

GET/v2/snapshots/{snapshot_id}

Read one snapshot's record. To read the files it holds, pass snapshot=<id> to tree, files, and files/content-url. Needs knowledge:read.

Capability knowledge:read

Parameters

NameInTypeDescription
snapshot_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl "https://api.mirabase.dev/v2/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}

Delete a snapshot

DELETE/v2/snapshots/{snapshot_id}

Delete a snapshot. Only its creator or the Space owner can, with knowledge:write. The versions it pinned stay. A second delete returns 404 snapshot_not_found.

Capability knowledge:write

Parameters

NameInTypeDescription
snapshot_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

  • 204 No response body

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
curl -X DELETE "https://api.mirabase.dev/v2/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

List snapshots

GET/v2/spaces/{space_id}/snapshots

List the snapshots of a Space, newest first. Needs knowledge:read.

Capability knowledge:read

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevSnapshot[]The items on this page.
next_cursorDevCursorPass it as cursor to get the next page. Absent on the last page.

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/snapshots" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "name": "research",
      "file_count": 1,
      "changes_cursor": "<cursor>",
      "created_by_principal_id": "<created_by_principal_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Take a snapshot

POST/v2/spaces/{space_id}/snapshots

Take a snapshot of the whole Space. Needs knowledge:write and editor; an Agent's write_mode does not apply, since nothing changes. Counts one write and no bytes. A Space holds at most 100 snapshots (409 too_many_snapshots) and a snapshot at most 10,000 files (409 snapshot_too_large, nothing is kept); a name in use returns 409 snapshot_name_taken. A busy Space returns 409 space_busy.

Capability knowledge:write

Guide: Sync, snapshots, and export

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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-KeyHeaderDevIdempotencyKeyThe 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 DevCreateSnapshotRequest

FieldTypeDescription
nameRequiredstring1 to 255 bytes, unique in the Space, no control characters, not starting with snp_.length 1..255

Responses

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
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/snapshots" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}