Quickstart

Braize answers questions from your own knowledge base, with a citation on every factual claim. This page gets you from a fresh account to a real, grounded answer over the REST API.

1. Create a workspace and add a source

Sign in, create a workspace (pick the region you want your data pinned to — this cannot be changed later without a migration), and add at least one source: upload a file or connect a website page. You can also click Try it on sample data to skip straight to step 3 while your own documents index.

2. Mint an API key

In the dashboard, go to Settings → API keys and create a key. Keys are prefixed bzk_ so they're recognizable in logs and diffs — treat the full value as a secret; it is shown once. Export it in your shell:

export BRAIZE_API_KEY="bzk_..."

3. Ask your first question

curl -s https://apibr.aize.dev/v1/query \
  -H "Authorization: Bearer $BRAIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What does this workspace know about?"}'

Every response is wrapped in an envelope: {"data": {...}, "meta": {...}}. data.blocks carries the answer's typed content blocks — citation blocks by default, plus a generated prose block if your workspace has include_generated_answers turned on. data.confidence is a 0–1 score; when Braize doesn't have grounding for your question, it says so rather than guessing.

4. Or retrieve passages instead of a generated answer

If you're building your own agent and want the ranked source passages without generation latency, call POST /v1/retrieve instead — same permission-aware search, no generation cost. Walkthrough: Agent-native retrieval (full request/response shape in the API reference).

What's next

• Authentication & regions — how API keys, regions, and the Braize-Version header work.
• Asking questions & streaming — every /v1/query field, plus the SSE event schema.
• Ingesting documents — upload, URL, and source ingestion beyond what you added during setup.
• Rate limits & quotas — the free-beta caps and what a 429 looks like.
• Handling errors — the RFC 9457 Problem shape every error uses.
• Setting up MCP — call Braize from Claude, Cursor, or any MCP-capable agent.
• Core concepts — why citations, ACL pre-filtering, and freshness are the product, not add-ons.
• API & MCP reference — every endpoint and tool, generated straight from the contract.