Core concepts

Three architectural choices shape everything Braize does. They're not features bolted onto a generic RAG pipeline — they're the reason the product exists.

1. Every claim is cited, or it isn't said

A groundedness check audits every generated answer before it ships; answering "I don't know" is a correct, expected outcome, not a failure mode. Concretely: data.blocks in a /v1/query response is a citation-first structure — citation blocks are always present, and a generated-prose text block is additive, opt-in per workspace (include_generated_answers). There is no code path that returns confident prose with nothing backing it.

This is why /v1/retrieve exists as a peer surface to /v1/query: if you're building your own agent, you may want the ranked passages and your own model's reasoning over them, rather than Braize's generated prose. Same retrieval, same citations, your choice of who does the synthesis.

2. Access control is a pre-filter inside the query, never a post-filter

Most "permission-aware" search systems retrieve broadly and then filter the results before showing them to the user. That shape is a leak waiting to happen — anything the filter forgets to strip is exposed at read time. Braize's retrieval query includes the ACL check as a condition of the search itself: a chunk a principal isn't permitted to see is never a candidate result, never scored, never returned. There's no separate step that could be skipped.

Google Drive already mirrors this: a file's explicit Drive sharing grants are captured into the same pre-filter, so a file's Drive-native permissions are still what decides who can ask Braize about it. As more connectors land (Notion, Slack, and beyond), each one will mirror its own source's permission model the same way.

3. Freshness is visible, not assumed

Every document carries a freshness score (0–100) and a last-indexed status. Re-ingesting a source updates its answers — the answer cache clears when the underlying document changes, not on a fixed schedule — so a stale answer is a visible, remediable state rather than a silent risk. Automated change-detection across sources (so Braize notices a source changed without you manually re-ingesting it) is on the roadmap; today, freshness is something you can see and act on, even where it isn't yet automatic.

How these three fit together

A typical /v1/query call: the ACL pre-filter narrows the candidate set to what the caller's identity can see → hybrid retrieval ranks passages within that set → a groundedness check runs against the generated answer → the response ships with citations pointing at exactly the passages that grounded it, each carrying its own freshness signal. Nothing in that chain is decorative — remove any one step and the product stops being what it claims to be.

What's next

• Handling errors — what it looks like when the system correctly refuses rather than guesses.
• The response envelope & versioning — the wire-level contract these principles are enforced through.