Build on Braize
Developer documentation for Braize: the REST API, agent-native /v1/retrieve, the OpenAI-compatible endpoint, and MCP (beta).
One permission-aware knowledge base, several surfaces. Generate a cited answer, retrieve ranked passages for your own agent, or call Braize as an OpenAI-compatible endpoint — all backed by the same retrieval and the same ACL pre-filter.
Two endpoints, one knowledge base
# Ask a question — cited, grounded answer
curl -s https://apibr.aize.dev/v1/query \
-H "Authorization: Bearer $BRAIZE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Ask a question about your knowledge base."}'
# Agent-native: ranked passages, no generation latency
curl -s https://apibr.aize.dev/v1/retrieve \
-H "Authorization: Bearer $BRAIZE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Search your knowledge base.", "top_k": 25}'Mint a workspace API key in the dashboard under Settings → API keys. The full walkthrough is the Quickstart.
Ways to call Braize
| Surface | What it does |
|---|---|
POST /v1/query | A grounded answer with a citation on every factual sentence, streaming over SSE. Abstains when the knowledge base doesn't cover the question. See Asking questions & streaming. |
POST /v1/retrieve | The same permission-aware hybrid retrieval, returning ranked passage text and provenance with no generation latency — for your own agent to reason over. See Agent-native retrieval. |
POST /v1/chat/completions | A drop-in for agent frameworks that already speak OpenAI: same pipeline, same ACL pre-filter, citations in an additive field. See OpenAI-compatible endpoint. |
| MCP | A standards-based endpoint AI agents discover and call — search_knowledge over the same retrieval. In beta: the contract and OAuth flow are live; client-compatibility verification is ongoing. See Setting up MCP. |
POST /v1/documents | Upload PDF / DOCX / XLSX / CSV / MD / HTML / images (multipart) or ingest a URL — parsed, sanitized, chunked, and embedded through the same pipeline. See Ingesting documents. |
| Widget | A lightweight, streaming, themeable embeddable widget — coming soon. The same answering engine is callable today over the REST and OpenAI-compatible endpoints in your workspace. |
Stable by design
The API follows an additive-only contract: every Braize-native response is an envelope, errors are RFC 9457 Problem Details with stable type URIs, pagination cursors are opaque, and heterogeneous outputs are typed content blocks. Clients should ignore unknown fields and event types — new capability arrives as new fields and new tools, never as breaking changes. See The response envelope & versioning and Handling errors.
Every endpoint, MCP tool, and schema is listed in the API & MCP reference — always kept in sync with the live API.