Backup and Restore

A snapshot captures a namespace’s configuration, documents, vectors and a manifest of its bucket objects. You restore a snapshot into a new namespace beside the source, or over the source itself. Every call takes your API key in Authorization: Bearer. The path names the source namespace by id or name.

Take a snapshot

import os, requests

BASE = "https://api.mixpeek.com/v1/namespaces/my-namespace"
H = {"Authorization": f"Bearer {os.environ['MIXPEEK_API_KEY']}"}

snap = requests.post(f"{BASE}/snapshots", headers=H, json={"copy_s3_objects": True}).json()
snapshot_id = snap["snapshot_id"]

const BASE = "https://api.mixpeek.com/v1/namespaces/my-namespace";
const H = {
  Authorization: `Bearer ${process.env.MIXPEEK_API_KEY}`,
  "Content-Type": "application/json",
};

const snap = await fetch(`${BASE}/snapshots`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ copy_s3_objects: true }),
}).then((r) => r.json());
const snapshotId = snap.snapshot_id;

curl -X POST "https://api.mixpeek.com/v1/namespaces/my-namespace/snapshots" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"copy_s3_objects": true}'

copy_s3_objects copies the bucket objects into the snapshot. Without it, the snapshot lists the objects and a restore reads them from the bucket. Set it if you might delete the namespace and restore it later. The snapshot runs in the background. GET /v1/namespaces/{namespace}/snapshots/{snapshot_id} shows its status.

Check that it can restore

report = requests.get(f"{BASE}/snapshots/{snapshot_id}/verify", headers=H, params={"deep": "true"}).json()

const report = await fetch(`${BASE}/snapshots/${snapshotId}/verify?deep=true`, { headers: H }).then((r) => r.json());

curl "https://api.mixpeek.com/v1/namespaces/my-namespace/snapshots/$SNAPSHOT_ID/verify?deep=true" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY"

Verify reads the snapshot and changes nothing. It lists what a restore would drop: a missing collection dump, unreachable vectors, or objects that are gone. deep=true also opens every collection dump and checks it is complete. After a restore from the snapshot, verify also returns that restore’s report.

Restore beside the source

Name a new namespace in target_namespace_name. The source keeps running and is not touched.

task = requests.post(
    f"{BASE}/snapshots/{snapshot_id}/restore",
    headers=H,
    json={"target_namespace_name": "my-namespace-restored"},
).json()

const task = await fetch(`${BASE}/snapshots/${snapshotId}/restore`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ target_namespace_name: "my-namespace-restored" }),
}).then((r) => r.json());

curl -X POST "https://api.mixpeek.com/v1/namespaces/my-namespace/snapshots/$SNAPSHOT_ID/restore" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_namespace_name": "my-namespace-restored"}'

The response returns a task_id. Poll GET /v1/tasks/{task_id} until the task completes. The restored namespace gets new ids, so it never collides with the source. History and telemetry stay with the source: tasks, retriever executions and interactions are not copied.

Restore to a point in time

restore_point restores the namespace as it was at an instant or at a WAL sequence number. It needs target_namespace_name.

requests.post(
    f"{BASE}/snapshots/{snapshot_id}/restore",
    headers=H,
    json={"target_namespace_name": "my-namespace-at-1800", "restore_point": "2026-10-01T18:00:00Z"},
)

await fetch(`${BASE}/snapshots/${snapshotId}/restore`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    target_namespace_name: "my-namespace-at-1800",
    restore_point: "2026-10-01T18:00:00Z",
  }),
});

curl -X POST "https://api.mixpeek.com/v1/namespaces/my-namespace/snapshots/$SNAPSHOT_ID/restore" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_namespace_name": "my-namespace-at-1800", "restore_point": "2026-10-01T18:00:00Z"}'

An instant is an RFC 3339 timestamp. The snapshot supplies the configuration: collections, retrievers and buckets. So pick a snapshot taken at or before the point. The vectors and payloads come from the write-ahead log, replayed to the point. A point outside the retained window is refused, and the error names the window you can use.

Restore onto an isolated shard

"isolated": true puts the restored copy on a temporary vector shard of its own. It needs target_namespace_name. Use it to check or measure a restore without load on the shared shard.

The isolated shard stops after six hours. Deleting the copy’s namespace stops it sooner.
One isolated copy runs at a time. A second request is refused, and the error names the namespace that holds it.

Restore in place

Leave out target_namespace_name and set confirm_in_place. The snapshot’s data replaces the namespace’s current data.

requests.post(f"{BASE}/snapshots/{snapshot_id}/restore", headers=H, json={"confirm_in_place": True})

await fetch(`${BASE}/snapshots/${snapshotId}/restore`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ confirm_in_place: true }),
});

curl -X POST "https://api.mixpeek.com/v1/namespaces/my-namespace/snapshots/$SNAPSHOT_ID/restore" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm_in_place": true}'

The current data is deleted. The namespace is read-only from when the restore is accepted until it finishes. A write in that window gets a 409 that asks you to retry later. A request without confirm_in_place is refused. To switch over with no read-only window, restore beside the source and point your traffic at the new namespace.

​Take a snapshot

​Check that it can restore

​Restore beside the source

​Restore to a point in time

​Restore onto an isolated shard

​Restore in place

​Related