Data export & portability API

Get your data — and your clients' data — back out: documents, derived memory, and the signed provenance ledger, over a self-serve, tenant-isolated API.

Portability is a trust primitive, not an afterthought. If you're the accountable party for your clients' data — a broker-owner, an agency principal, a compliance lead — "can I get it back out?" is a standard security-questionnaire and DPA line item. Aether's answer is a documented API you can script yourself: no support ticket, no manual process, and an export you can cryptographically verify against the same Ed25519-signed ledger that powers the audit & provenance API.

All four endpoints are read-only and tenant-isolated: your API key determines the tenant, and you only ever export what that tenant owns.

The aether-export/v1 format

An export is a manifest plus three paged sections. Every response carries "format": "aether-export/v1"; reject an archive whose parts disagree on it.

Direct REST requests authenticate with Authorization: Bearer <api-key>. All sections page with offset / limit and return total + has_more.

What an export contains

Documents (/v1/export/documents) — one record per active document: doc_id, BLAKE3 cid, title, content type, size, version, timestamps, tags, source, partition, entity_id, structured metadata, the intra-tenant acl_readers labels (so your access policy survives the move), and the derived retrieval passages. Pass include_content=true to inline the original bytes as content_base64 (page cap drops to 50; a per-document content_error field keeps one unreadable document from failing the page — retry it via GET /v1/documents/{id}/download).

Soft-deleted (tombstoned) documents are not part of the live export, and hard-deleted content is gone by design — but both leave their full signed history in the ledger section.

Memory (/v1/export/memory) — one group per memory scope, i.e. per (partition, owner entity) pair. Each group contains that owner's entities, relationships, and facts. Superseded and retracted facts are included deliberately: an exiting tenant is owed the history, and invalid_from / supersedes_fact_id tell the story.

Ledger (/v1/export/ledger) — every signed event your tenant may see, in causal (Lamport) order, in the same envelope the audit API serves: at, actor, action, resource, outcome, source: "ledger", and a proof with content_id, lamport, node_id, public_key, signature, and the server's own re-check verified. This includes the trail of documents that were hard-deleted — the deletion is provable long after the content is unrecoverable.

Verifying an export

The export verifies the same way the audit trail does — see proving the chain wasn't tampered with:

1. Every ledger record must have proof.verified: true (the engine re-checks each signature at read time).
2. Verify independently: check the Ed25519 signature with the record's public_key, and confirm node_id == BLAKE3(public_key). The manifest's verification block gives you the node's identity to pin against.
3. Cross-check content: a content-bearing event's proof.content_id is the BLAKE3 id of the document bytes — compare it against the cid (and, if you exported content, the hash of the decoded bytes) in the documents section.

Scoping: whole tenant, one partition, one principal

• Single-tenant keys export the whole tenant by default, or one partition with ?partition=<key>.
• Multi-tenant (mode B) keys must name a partition on every call — the per-end-user export. If one of your customers asks for their data, scope the export to their partition and hand them exactly their slice.
• Read-ACLs apply. A non-admin key exports only the documents its asserted principal (?acting_principal= / ?acting_groups=) may read, and the ledger section is filtered the same way. Admin-role keys bypass ACLs — and that bypass is recorded.
• Exports are audited. Every page served writes a tenant.export audit event, plus an export record in the opt-in access-audit log (GET /v1/audit/access?action=export) — so "who exported what, when" is itself answerable.

Example: a complete, verified export

KEY="your-api-key"
API="https://api.aetherdb.ai/v1"

# 1. The manifest — totals to check against, and the signer to pin.
curl -s "$API/export" -H "Authorization: Bearer $KEY" > manifest.json

# 2. Documents, with content, paged.
offset=0
while : ; do
  page=$(curl -s "$API/export/documents?include_content=true&offset=$offset&limit=50" \
    -H "Authorization: Bearer $KEY")
  echo "$page" >> documents.jsonl
  [ "$(echo "$page" | jq .has_more)" = "true" ] || break
  offset=$((offset + $(echo "$page" | jq .count)))
done

# 3. Memory and ledger, same loop shape.
curl -s "$API/export/memory?limit=200"  -H "Authorization: Bearer $KEY" > memory.json
curl -s "$API/export/ledger?limit=1000" -H "Authorization: Bearer $KEY" > ledger.json

# 4. Verify: counts match the manifest, every proof re-verified.
jq '[.documents.total, .memory.scopes, .ledger.events]' manifest.json
jq '[.records[].proof.verified] | all' ledger.json   # must be true

For procurement & DPA reviews

The short version your security questionnaire wants:

• Scope: a tenant can export all of its documents (including original content), all derived memory (including history), and its complete signed mutation ledger, via a documented self-serve API — no vendor involvement required.
• Format: JSON (aether-export/v1), paged, with authoritative totals in a manifest; document content is base64 inline or per-document download.
• Integrity: every ledger record is independently verifiable (Ed25519 signature + BLAKE3 content id); the export is tamper-evident, not just a dump.
• Per-data-subject portability: partition-scoped exports isolate one end-user's slice (GDPR Art. 20 support for your own customers).
• Deletion: the corresponding erasure path is hard deletion (DELETE /v1/documents/{id}?hard=true), which destroys the encryption key irreversibly — and the ledger section retains the signed proof that the deletion happened, exportable even after the data is gone.
• Accountability: exports themselves are logged (tenant.export + access-audit export records), including admin-bypass visibility.