# Sync, snapshots, and export

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`](https://mirabase.io/developers/api/tree.md#tree-list) for the state at one moment, and [`GET /v2/spaces/{space_id}/changes`](https://mirabase.io/developers/api/changes.md#changes-list) 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:

```bash
# 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"
```

TypeScript:

```ts
// Every page of the tree, plus the first page's changes_cursor.
const { nodes, changesCursor } = await mirabase.tree.snapshot("/", { recursive: true });
for (const node of nodes) mirror(node);

// Long-polls, follows has_more, and reconnects after failures it can retry.
for await (const change of mirabase.changes.watch({ cursor: changesCursor })) apply(change);
```

Python:

```python
# Every page of the tree, plus the first page's changes_cursor.
nodes, cursor = mb.tree.snapshot(recursive=True)
for node in nodes:
    print(node["path"])

# Long-polls, follows has_more, and reconnects after failures it can retry.
for change in mb.changes.watch(cursor=cursor):
    print(change["op"], change.get("path"))
```

- 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](https://mirabase.io/developers/api/schemas.md#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](https://mirabase.io/developers/branches.md#reads).

## See recent changes

When several people or Agents share a Space, call [`GET /v2/spaces/{space_id}/activity`](https://mirabase.io/developers/api/changes.md#changes-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`](https://mirabase.io/developers/api/webhooks.md#webhooks-create). Mirabase delivers batches of events in order, one batch in flight at a time, at least once; the request body is described in [DevWebhookPayload](https://mirabase.io/developers/api/schemas.md#DevWebhookPayload).

curl:

```bash
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:

```ts
const webhook = await mirabase.webhooks.create({
  url: "https://hooks.example.com/mirabase",
  ops: ["create", "update", "delete"],
});
// Store webhook.secret now: it is in this response only.

for await (const delivery of mirabase.webhooks.deliveries(webhook.id)) console.log(delivery.attempt, delivery.outcome);
```

Python:

```python
webhook = mb.webhooks.create({
    "url": "https://hooks.example.com/mirabase",
    "ops": ["create", "update", "delete"],
})
# Store webhook["secret"] now: it is in this response only.

for delivery in mb.webhooks.deliveries(webhook["id"]):
    print(delivery["attempt"], delivery["outcome"])
```

TypeScript:

```ts
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);
```

Python:

```python
import os

from mirabase import parse_webhook


def receive(header: str | None, body: bytes) -> None:
    """header is the Mirabase-Signature header, body the raw request body."""
    # Verify against the raw body, before parsing JSON. Raises ValueError on a bad or stale signature.
    payload = parse_webhook(secret=os.environ["MIRABASE_WEBHOOK_SECRET"], header=header, body=body)
    # Dedupe on payload["delivery_id"]: a retry resends the same batch.
    for change in payload["events"]:
        print(change["op"], change.get("path"))
```

- Verify the signature of every request as in the example above; the signature format and the timestamp tolerance are in [DevWebhook](https://mirabase.io/developers/api/schemas.md#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](https://mirabase.io/developers/api/schemas.md#DevWebhook).
- The secret is in the create response only. If you lose it, call [`POST /v2/webhooks/{webhook_id}/rotate-secret`](https://mirabase.io/developers/api/webhooks.md#webhooks-rotatesecret).

When deliveries stop, `status` becomes `disabled` and [disabled_reason](https://mirabase.io/developers/api/schemas.md#DevWebhook.disabled_reason) says why. [`PATCH /v2/webhooks/{webhook_id}`](https://mirabase.io/developers/api/webhooks.md#webhooks-update) with `{status: "active"}` reopens the webhook, and [`GET /v2/webhooks/{webhook_id}/deliveries`](https://mirabase.io/developers/api/webhooks.md#webhooks-deliveries) lists the delivery attempts.

## Take a snapshot

[`POST /v2/spaces/{space_id}/snapshots`](https://mirabase.io/developers/api/snapshots.md#snapshots-create) records every file's path and version at this moment. Versions are immutable, so a snapshot copies no bytes.

curl:

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

TypeScript:

```ts
const snapshot = await mirabase.snapshots.create("before-import");

const then = await mirabase.files.readText("/notes/hello.md", { snapshot: "before-import" });
for await (const node of mirabase.tree("/", { recursive: true, snapshot: snapshot.id })) console.log(node.path);

// Everything written after the snapshot, with no gap and no overlap.
for await (const change of mirabase.changes.watch({ cursor: snapshot.changes_cursor })) apply(change);
```

Python:

```python
snapshot = mb.snapshots.create("before-import")

# Read a file as the snapshot pinned it, by name or id.
then = mb.files.read("/notes/hello.md", snapshot="before-import").text()
for node in mb.tree("/", recursive=True, snapshot=snapshot["id"]):
    print(node["path"])

# Everything written after the snapshot, with no gap and no overlap.
for change in mb.changes.watch(cursor=snapshot["changes_cursor"]):
    print(change["op"], change.get("path"))
```

- 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`](https://mirabase.io/developers/api/transfers.md#transfers-createexport) exports files as a tar archive, and [`POST /v2/spaces/{space_id}/imports`](https://mirabase.io/developers/api/transfers.md#transfers-createimport) 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](https://mirabase.io/developers/conventions.md#jobs).

curl:

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

TypeScript:

```ts
const exported = await mirabase.transfers.startExport({ snapshot: "before-import" });
// ...poll mirabase.jobs.get(exported.job_id) until it succeeded, then:
const archive = await mirabase.transfers.archiveUrl(exported.job_id);

// Put the archive somewhere as a file, then import it into another Space.
const written = await mirabase.files.write("/imports/space.tar", await (await fetch(archive.url)).blob(), {
  space: otherSpaceId,
  contentType: "application/x-tar",
});
const imported = await mirabase.transfers.startImport(
  { source_entry_id: written.entry.id, path: "/", on_conflict: "skip" },
  { space: otherSpaceId },
);
```

Python:

```python
from urllib.request import urlopen

exported = mb.transfers.start_export({"snapshot": "before-import"})
# Polls until status is succeeded, failed, or cancelled.
mb.jobs.wait(exported["job_id"])
archive = mb.transfers.archive_url(exported["job_id"])

# Put the archive in another Space as a file, then import it there. other_space_id is that Space's id.
uploaded = mb.files.write(
    "/imports/space.tar",
    urlopen(archive["url"]).read(),
    space=other_space_id,
    content_type="application/x-tar",
)
imported = mb.transfers.start_import(
    {"source_entry_id": uploaded["entry"]["id"], "path": "/", "on_conflict": "skip"},
    space=other_space_id,
)
```

### 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`](https://mirabase.io/developers/api/transfers.md#transfers-archiveurl).

> **Warning:** 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`](https://mirabase.io/developers/api/transfers.md#transfers-createfork)) 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](https://mirabase.io/developers/branches.md): give an Agent a workspace it can throw away.
- [API conventions](https://mirabase.io/developers/conventions.md#jobs): follow jobs such as exports and imports.
- [Error codes](https://mirabase.io/developers/errors.md#codes): what to do about codes such as `cursor_expired`.
