Aether Docs

Query a document's cryptographically signed history — what happened to it, when, and which node vouched for it.

Every mutation Aether makes to a document is recorded as an Ed25519-signed event in an append-only provenance ledger: insert, update, tombstone, restore, re-embed, and GDPR hard-delete. The audit API exposes that trail so you can prove, cryptographically, the lineage of any record — the accountability surface regulated AI deployments need and the commodity vector layer doesn't have.

The endpoint is read-only and tenant-isolated: you only ever see the lineage of documents your own tenant owns. A doc_id that belongs to another tenant — or doesn't exist — returns the identical 404, so the route can't be used to probe for documents across tenants.

SDK method

lineage is a method on the AetherClient. It takes a doc_id and returns the document's audit records, oldest-first in causal order.

Operation	Python	TypeScript	.NET	Go
Document lineage / provenance	`lineage`	`lineage`	`GetLineageAsync`	`Lineage`

The moat, exposed

The signed ledger already powered Aether's node sync and durability. This API surfaces it as a product feature — "cryptographically auditable memory" — without exposing any engine internals or key material.

Route contract

Method	Path	Description
`GET`	`/v1/audit/records/{doc_id}`	The document's signed event history, oldest-first. `404` for an unknown or cross-tenant id.

Direct REST requests authenticate with Authorization: Bearer <api-key>. SDK users construct the client with an API key and let the SDK attach it.

Response shape

Each record shares one envelope; ledger events set source: "ledger" and carry a proof.

Field	Type	Description
`at`	string	RFC 3339 timestamp of the event.
`actor`	string	The signing node (`node:<hex>`) — the cryptographic party that vouched for the event.
`action`	string	`document.inserted` · `document.updated` · `document.tombstoned` · `document.restored` · `document.reembedded` · `document.hard_deleted`.
`resource`	string	`document:<uuid>`.
`outcome`	string	`committed`.
`source`	string	`ledger`.
`proof.content_id`	string?	BLAKE3 content id — present on content events (insert/update), omitted otherwise.
`proof.lamport`	number	Causal position in the ledger.
`proof.node_id`	string	Signing node id, hex. Equals `BLAKE3(public_key)`.
`proof.public_key`	string	Ed25519 signer public key, hex (32 bytes).
`proof.signature`	string	Ed25519 signature, hex.
`proof.verified`	boolean	Whether the engine re-verified this signature at read time.

Proving the chain wasn't tampered with

The trail is tamper-evident. Each event is signed with the node's Ed25519 key, and the signing node's identity is bound to its key by construction: node_id == BLAKE3(public_key). Any change to a recorded event — a rewritten timestamp, a swapped content id — invalidates its signature.

Two things make this checkable rather than a promise:

The engine re-verifies every signature on each read. proof.verified reflects that check. If any record comes back false, the ledger has been tampered with or corrupted — treat the trail as broken from that record onward. A healthy trail is verified: true on every record.
The proof material is yours to inspect. Each record hands you the signature, the signer's public_key, and the node_id. You don't have to trust Aether's word: confirm node_id == BLAKE3(public_key) yourself, and pin the set of public keys your nodes may sign with so any record from an unexpected key is rejected.

Example

from aether import AetherClient

client = AetherClient(api_key="...")

doc = client.insert_text("Patient intake note", tags=["phi"])
records = client.lineage(doc.doc_id)

for r in records:
    ok = "✓" if r.proof and r.proof.verified else "✗"
    print(f"{ok} {r.at}  {r.action}  by {r.actor}")

# Fail loud if the chain doesn't verify end to end.
assert all(r.proof and r.proof.verified for r in records), "provenance chain broken"

Or straight against the REST surface:

Bash

curl -s https://api.aetherdb.ai/v1/audit/records/$DOC_ID \
  -H "Authorization: Bearer $AETHER_API_KEY" | jq

Notes & limits

Retained history. The trail covers the ledger history the node currently retains. Events folded into a checkpoint and truncated before a restart may not appear; the document's current state always survives. Full historical replay is a later enhancement.
Hard-deleted documents. A GDPR hard-delete shreds the document's encryption key and purges its content, but the event that it happened stays in the ledger — so the owning tenant can still retrieve the deletion trail as proof that "right to be forgotten" was honored.