Agent-native retrieval

If you're building your own agent and already have a model to reason with, POST /v1/retrieve gives you the ranked, cited source passages directly — no generation latency, because there's no generation step. It's the same permission-aware hybrid retrieval /v1/query uses internally, and it backs the MCP search_knowledge tool.

Request

curl -s https://apibr.aize.dev/v1/retrieve \
  -H "Authorization: Bearer $BRAIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "refund policy", "top_k": 25}'

Response

{
  "data": {
    "passages": [
      {
        "text": "…",
        "score": 0.87,
        "document_id": "…",
        "document_version": "…",
        "title": "Refund Policy",
        "source_ref": "refund-policy.pdf",
        "heading_path": ["Policies", "Refunds"],
        "context_prefix": "…"
      }
    ]
  },
  "meta": { "request_id": "…", "braize_version": "2026-09-01" }
}

• score is a normalized rerank relevance in [0, 1] — higher is more relevant, not a probability.
• heading_path locates the passage inside its source document (useful for citing "Policies → Refunds" rather than just a filename).
• context_prefix is the situating sentence the passage was indexed with — it helps a downstream model interpret a passage pulled out of context.
• Passages return text and provenance only — never embeddings.

Why not always use /v1/retrieve?

Use /v1/query when you want Braize to also synthesize the answer (a human channel, a chat UI). Use /v1/retrieve when your own model will do the reasoning — an agent, a custom RAG pipeline, or anything calling through MCP's search_knowledge. Same ACL pre-filter either way: an identity only ever gets passages it's permitted to see.

What's next

• Setting up MCP — search_knowledge is this endpoint, exposed as a tool.
• Full request/response schema: API reference.