Core concepts
Classification, ACL tokens, the public/private bifurcation, and snapshot-pinned reads — the model behind every response.
Four ideas explain every field in this API.
Classification — a property of the data
Every chunk is stamped with a classification at ingest, immutable thereafter. It describes the data, not the request.
Prop
Type
Audience — a property of the request
The audience describes the caller and is derived from the API key, never
client-supplied: end_customer or internal_agent. Classification (data) and
audience (request) are orthogonal — access is where they meet.
ACL tokens — where they meet
Rather than query separate "public" and "private" databases and merge, the brain flattens each chunk's access rules into an ACL token set at ingest, and every retrieval filters on it in one pass:
computeAcl(classification, subjectId) →
public → ["public"]
internal → ["internal"]
confidential + subject 5591 → ["confidential", "subject:5591"]A caller sees a chunk iff the tokens its key holds intersect the chunk's ACL.
So a confidential booking about customer 5591 is visible to an internal agent
and to customer 5591 acting on their own behalf — but never to an anonymous
visitor, who holds only ["public"]. Public and private results come back in
one fusible ranked list.
The bifurcation invariant
Anonymous callers see public knowledge only. A customer sees public plus their own records — never internal playbooks. An internal agent fuses both. This invariant is enforced at retrieval time by the ACL intersection, and you can inspect exactly which tokens a key holds via POST /v1/policy/resolve.
Snapshots — reproducible reads
Every response carries a snapshotId — an encoded
(pipeline_version, log_offset, index_build_id) — and a policyBundleRevision.
Together they make a read reproducible: pin the snapshot and the same query
returns the same chunks, even as new data is ingested. Knowledge is pinnable;
policy and ACLs are never pinned (a revoked grant takes effect immediately).
Retrieval modes
mode trades latency for recall:
Prop
Type