Snapshots

A snapshot is a restorable copy of one index that you own and control. It is not the platform's engine backup (operators take those with /admin/snapshot); it belongs to your organization and travels through the public API.

What a snapshot containsCopy Anchor Link

The manifest is written last: a snapshot without a manifest is incomplete and is never listed.

New snapshots contain masked embedding credential references. Restore uses the current key for the same provider and endpoint; it never restores a historical snapshot key. If no matching connection exists, the job fails before switching the live search.

CreateCopy Anchor Link

curl -sS -X POST "$AAC_API/indexes/products/snapshots" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"job_id": "clx9a4...",
	"snapshot_id": "snap_mh3k2a1b0f3c9e7d21a",
	"status": "queued",
	"pruned": [],
	"request_id": "req_..."
}

The call answers 202 and queues a snapshot job. Poll GET /jobs/{jobId} until it is completed. Creating needs both settings:write and documents:write.

Plan limitsCopy Anchor Link

At the limit the call is refused with 409 SNAPSHOT_LIMIT_REACHED. Retry with ?prune=true to delete the oldest snapshots first. A daily job deletes snapshots older than the retention window, but the newest snapshot of every index is always kept, however old.

List, inspect, downloadCopy Anchor Link

curl -sS "$AAC_API/indexes/products/snapshots" -H "Authorization: Bearer $AAC_KEY"
curl -sS "$AAC_API/indexes/products/snapshots/snap_mh3k2a1b0f3c9e7d21a" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"snapshot": {
		"id": "snap_mh3k2a1b0f3c9e7d21a",
		"index": "products",
		"created_at": "2026-10-25T09:12:44.000Z",
		"document_count": 18420,
		"bytes": 9481231,
		"engine_version": "30.2",
		"embed_model": "openai/text-embedding-3-small",
		"checksum": "9f2c…",
		"counts": {
			"synonyms": 14,
			"curations": 3,
			"stemming": 0,
			"stopwords": 1,
			"rules": 6,
			"profiles": 2
		}
	},
	"download": {
		"url": "https://storage.example.com/…",
		"expires_at": "2026-10-25T09:27:44.000Z",
		"content_encoding": "gzip",
		"format": "ndjson"
	},
	"request_id": "req_..."
}

The download URL is signed for 15 minutes and points at the documents file. Listing and reading need documents:read.

RestoreCopy Anchor Link

curl -sS -X POST "$AAC_API/indexes/products/snapshots/snap_mh3k2a1b0f3c9e7d21a/restore" \
  -H "Authorization: Bearer $AAC_KEY"

Answers 202 {job_id, status}. The restore job builds a new collection from the snapshot, replays the ranking configuration and swaps the alias atomically — exactly like a reindex. The replaced collection is kept as the job's rollback collection. While a reindex or another restore is queued or running the call answers 409 JOB_CONFLICT.

IsolationCopy Anchor Link

Storage keys contain the organization and index ids. A snapshot id of another tenant — or of another index of yours — is a plain 404 SNAPSHOT_NOT_FOUND.

Known limitsCopy Anchor Link

• The worker streams exported documents and restores bounded batches. Restore retains record metadata until reconciliation, so memory use still grows with the number of documents.
• Snapshots are per index; there is no organization-wide snapshot.

Before publication, restore verifies hashes and sizes of every configuration file and compressed documents, plus the record count. A schema, provider-key or settings edit during loading prevents the stale restore from switching search; retry uses the current configuration. Private-field restrictions from both the current settings and snapshot are retained. Relax them through a separate settings change after restore.