Skip to content
Developer docs
Docs menu

Sync, snapshots, and export

Markdown

Mirror a Space with the tree, the change feed, and webhooks, pin a moment with snapshots, and move a whole Space with export and import.

Sync uses two endpoints: GET /v2/spaces/{space_id}/tree for the state at one moment, and GET /v2/spaces/{space_id}/changes for what happened after it.

Run the sync loop

  1. Read tree and keep the changes_cursor from the first page. Paging is not one snapshot, and the first page's cursor covers writes made while you page.
  2. Pass the cursor to changes and apply the events.
  3. Continue with the response's cursor. When has_more is true, call again right away; otherwise, long-poll with wait.
curl
# First page of the tree. Keep its changes_cursor.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree?recursive=true" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Then follow the feed, waiting up to 30 seconds when nothing has changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/changes?cursor=$CURSOR&wait=30" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • Without cursor the feed starts from now, so read tree first for a full sync.
  • An expired cursor returns 410 cursor_expired: read tree again and continue from the new changes_cursor. How long events are kept and the limits on long polling are in the reference.

Events

Each event's op is create, update, move, delete, or restore; what each means is in DevChangeOp.

Apply events

  • Events can repeat, including what tree already showed, so apply them idempotently by entry_id.
  • move carries only the new path, so keep your own map from entry_id to path, starting from tree.
  • Directories produce no events of their own, so use tree to see empty directories appear or go.
  • An Agent's private memory is not in the feed.
  • With branch you get the branch's own feed, with a different shape and rules. See Branches and mounts.

See recent changes

When several people or Agents share a Space, call GET /v2/spaces/{space_id}/activity before starting work: it is the change feed of the last few days already summed up per principal and per Entry, so you do not have to read changes from the start and fold it yourself.

Receive webhooks

Instead of polling changes, subscribe to main's changes with POST /v2/spaces/{space_id}/webhooks. Mirabase delivers batches of events in order, one batch in flight at a time, at least once; the request body is described in DevWebhookPayload.

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mirabase", "ops": ["create", "update", "delete"]}'
TypeScript
import { parseWebhook } from "@mirabase/sdk/developer";

// Verify against the raw body, before parsing JSON. Throws on a bad or stale signature.
const payload = await parseWebhook({
  secret: process.env.MIRABASE_WEBHOOK_SECRET!,
  header: request.headers.get("Mirabase-Signature"),
  body: await request.text(),
});
// Dedupe on payload.delivery_id: a retry resends the same batch.
for (const change of payload.events) apply(change);
  • Verify the signature of every request as in the example above; the signature format and the timestamp tolerance are in DevWebhook.
  • Dedupe on Mirabase-Delivery-Id, the same as delivery_id: a retry resends the same batch. Apply events by entry_id.
  • Return 2xx quickly and do slow work after you respond. What counts as a failure, and how retries are spaced, are in DevWebhook.
  • The secret is in the create response only. If you lose it, call POST /v2/webhooks/{webhook_id}/rotate-secret.

When deliveries stop, status becomes disabled and disabled_reason says why. PATCH /v2/webhooks/{webhook_id} with {status: "active"} reopens the webhook, and GET /v2/webhooks/{webhook_id}/deliveries lists the delivery attempts.

Take a snapshot

POST /v2/spaces/{space_id}/snapshots records every file's path and version at this moment. Versions are immutable, so a snapshot copies no bytes.

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": "before-import"}'

# Read a file as the snapshot pinned it, by name or id.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md&snapshot=before-import" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • Pass snapshot=<id or name> to tree, files, and files/content-url to read the version the snapshot pinned, even after the file changed, moved, or went to the trash.
  • The snapshot's changes_cursor continues changes from the same moment, so a snapshot plus the feed is a full sync with no gap and no overlap.
  • A snapshot holds files with a path only: empty directories, memories, and ingested URLs and text are not in it.

Export and import

POST /v2/spaces/{space_id}/exports exports files as a tar archive, and POST /v2/spaces/{space_id}/imports imports a tar or gzip-compressed tar into a Space. Both run as jobs and return 202 with job_id; follow them as described in API conventions.

curl
# Export as a job, then follow it with GET /v2/jobs/$JOB_ID
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/exports" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot": "before-import"}'

# Once it succeeded: a signed download, valid up to five minutes.
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID/content-url" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Import a tar that is already a file you can read, into another Space.
curl -X POST "https://api.mirabase.dev/v2/spaces/$OTHER_SPACE_ID/imports" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_entry_id": "'$ARCHIVE_ENTRY_ID'", "path": "/", "on_conflict": "skip"}'

Export

  • The file list is fixed when the job starts, so the archive is one moment of the Space, or the snapshot's with snapshot.
  • Only files are included: content without a path, memories, and version history are not in it. The archive format is in the reference.
  • When the job succeeds, get a download URL for the archive with GET /v2/jobs/{job_id}/content-url.
An archive is kept for 7 days. Purging any file in the Space, or setting or changing the read_root of the member who started the export, makes the archive unavailable at once: export again.

Import

  • Put the archive in any Space first with PUT .../files or uploads; source_entry_id is its Entry id.
  • An archive this API exported comes back at the same paths with the same media types, so export and import round-trip. Any other archive lands under path.
  • Each file is written like PUT, under the same path rules, write roots, write_mode, and quotas, and an import never becomes a proposal.
  • An import is not atomic: a member that cannot be written does not stop the job and counts in result.failed, and when a quota runs out the job stops and keeps what it has imported.

Coming soon

Forking a Space (POST /v2/spaces/{space_id}/forks) is coming soon. Until then, take a snapshot, export it with snapshot, create a Space, and import the archive there.

Next steps