Sync, snapshots, and export
MarkdownMirror 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
- Read
treeand keep thechanges_cursorfrom the first page. Paging is not one snapshot, and the first page's cursor covers writes made while you page. - Pass the cursor to
changesand apply the events. - Continue with the response's
cursor. Whenhas_moreistrue, call again right away; otherwise, long-poll withwait.
# 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
cursorthe feed starts from now, so readtreefirst for a full sync. - An expired cursor returns 410
cursor_expired: readtreeagain and continue from the newchanges_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
treealready showed, so apply them idempotently byentry_id. movecarries only the new path, so keep your own map fromentry_idto path, starting fromtree.- Directories produce no events of their own, so use
treeto see empty directories appear or go. - An Agent's private memory is not in the feed.
- With
branchyou 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 -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"]}'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 asdelivery_id: a retry resends the same batch. Apply events byentry_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 -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>totree,files, andfiles/content-urlto read the version the snapshot pinned, even after the file changed, moved, or went to the trash. - The snapshot's
changes_cursorcontinueschangesfrom 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.
# 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.
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 .../filesoruploads;source_entry_idis 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
- Branches and mounts: give an Agent a workspace it can throw away.
- API conventions: follow jobs such as exports and imports.
- Error codes: what to do about codes such as
cursor_expired.
