API & MCP reference

Every REST endpoint and MCP tool available in the Braize API, with request and response schemas — always in sync with the live API.

Every endpoint, tool, and schema below reflects the Braize API exactly as it runs today. The API evolves additively: new fields and tools are added, but existing ones never change or disappear — so your integration keeps working.

REST API

REST API version 2026-09-01. New fields and endpoints are only ever added — existing ones never change or disappear.

Ask questions

POST/v1/query

Ask a question against the workspace knowledge base

Parameters

Field	Type	Required	Description
`Braize-Version (header)`	string (date)	No	Override the workspace's pinned contract version.

Request body: QueryRequest

Responses

200 — Answer with citations → QueryResponseEnvelope
503 — Answer generation temporarily unavailable (upstream inference provider outage). RFC 9457 Problem with type https://braize.app/errors/generation-unavailable and a Retry-After header (seconds). → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Agent-native retrieval

POST/v1/retrieve

Retrieve ranked, cited passages (no answer generation; for agents/MCP)

Parameters

Field	Type	Required	Description
`Braize-Version (header)`	string (date)	No	Override the workspace's pinned contract version.

Request body: RetrieveRequest

Responses

200 — Ranked passages with provenance → RetrieveResponseEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

OpenAI-compatible

POST/v1/chat/completions

OpenAI-compatible chat completion over the workspace knowledge base

Thin adapter over the same query pipeline as POST /query — same retrieval, same ACL pre-filter, same grounding, same metering, same request logs. Stateless like OpenAI (the client resends history each call); each call opens a fresh conversation whose id rides in `braize`. Unknown request fields (n, tools, max_tokens, …) are accepted and ignored (must-ignore). Errors are OpenAI-shaped ChatCompletionError objects, NOT RFC 9457 — see the contract-stance note above.

Request body: ChatCompletionRequest

Responses

200 — Chat completion ("chat.completion"). With "stream": true the response is text/event-stream in OpenAI data-only SSE framing (no `event:` names): every frame's `data:` payload is a ChatCompletionChunk; the final chunk carries finish_reason, usage, and the `braize` extension; the stream terminates with `data: [DONE]`. → ChatCompletionResponse
default — OpenAI-shaped error object (NOT RFC 9457 — owner-approved deviation confined to this compatibility surface). → ChatCompletionError

Documents

GET/v1/documents

List documents in the workspace knowledge base

Parameters

Field	Type	Required	Description
`limit (query)`	integer	No	Maximum rows returned for this page (newest first).
`cursor (query)`	string	No	OPAQUE forward page token from a prior response's `next_cursor` (AIP-158). Clients MUST treat it as opaque and never parse it.
`q (query)`	string	No	Case-insensitive substring search over title, upload filename/URL, source name, and class. Spans the whole corpus, not just one page.
`source_id (query)`	string (uuid)	No	Only documents belonging to this source.
`sync_status (query)`	string	No	Only documents whose sync lifecycle state matches. Current values: queued, downloading, processing, indexed, failed. New values are additive forever; an unknown value matches nothing (empty page).

Responses

200 — Document list → DocumentListEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/documents

Ingest a document via multipart upload (≤ 100MB)

Parameters

Field	Type	Required	Description
`mode (query)`	string	No	Legacy — ignored. Ingestion is always asynchronous: the server enqueues and returns 202 immediately; poll GET /documents/{id}.

Request body: object

Responses

200 — Ingest result (synchronous path) → IngestResultEnvelope
202 — Ingestion accepted (async path) — parse/embed happen out of band → IngestPendingEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/documents/url

Ingest a document from a URL

Parameters

Field	Type	Required	Description
`mode (query)`	string	No	Legacy — ignored. Ingestion is always asynchronous: the server fetches the page, enqueues, and returns 202 immediately.

Request body: UrlIngestRequest

Responses

200 — Ingest result (synchronous path) → IngestResultEnvelope
202 — Ingestion accepted (async path) - parse/embed happen out of band → IngestPendingEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

GET/v1/documents/{document_id}

Document detail with version history

Parameters

Field	Type	Required	Description
`document_id (path)`	string (uuid)	Yes

Responses

200 — Document detail → DocumentDetailEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

DELETE/v1/documents/{document_id}

Soft-delete a document and enqueue a content purge

Parameters

Field	Type	Required	Description
`document_id (path)`	string (uuid)	Yes

Responses

200 — Delete result → DeleteResultEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/documents/{document_id}/refresh

Re-ingest a URL-backed document so its answers reflect the latest content

Parameters

Field	Type	Required	Description
`document_id (path)`	string (uuid)	Yes

Responses

200 — Ingest result (a new version of the document) → IngestResultEnvelope
202 — Refresh accepted — re-ingest happens out of band → IngestPendingEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Sources & connectors

GET/v1/sources

List connectors / sources in the workspace

Responses

200 — Source list → SourceListEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/sources

Create a draft connector source (wizard first step)

Request body: CreateSourceRequest

Responses

201 — Draft source created → SourceDraftEnvelope
400 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
403 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/sources/{source_id}/activate

Activate a draft connector source (wizard final step)

Parameters

Field	Type	Required	Description
`source_id (path)`	string (uuid)	Yes

Responses

200 — Source activated (or already active — idempotent) → ActivateSourceResponseEnvelope
400 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
403 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
404 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

GET/v1/sources/{source_id}

One source's summary — health, counts, live sync progress

Parameters

Field	Type	Required	Description
`source_id (path)`	string (uuid)	Yes

Responses

200 — Source summary → SourceSummaryEnvelope
404 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

DELETE/v1/sources/{source_id}

Disconnect a source and remove all data it indexed

Parameters

Field	Type	Required	Description
`source_id (path)`	string (uuid)	Yes

Responses

200 — Source disconnected (or already archived — idempotent) → DisconnectSourceResponseEnvelope
403 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
404 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/sources/{source_id}/sync

Trigger an on-demand sync for a connected source

Parameters

Field	Type	Required	Description
`source_id (path)`	string (uuid)	Yes

Responses

202 — Sync requested — poll GET /sources for progress. → TriggerSyncResponseEnvelope
400 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
403 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
404 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
502 — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

GET/v1/connectors

Connector catalog — every connector kind, its capabilities, ACL fidelity, and plan availability

Responses

200 — Connector catalog (the manifest the dashboard renders from) → ConnectorCatalogEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Conversations

GET/v1/conversations/{conversation_id}

Conversation message history

Parameters

Field	Type	Required	Description
`conversation_id (path)`	string (uuid)	Yes

Responses

200 — Conversation history → ConversationHistoryEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Request log

GET/v1/requests

List recent API requests recorded for the workspace (admin scope)

Parameters

Field	Type	Required	Description
`status (query)`	string	No	failed = only requests with status_code >= 400. Servers treat unknown values as the default behavior (all).
`limit (query)`	integer	No	Maximum number of rows returned (newest first).

Responses

200 — Request log list (newest first) → RequestLogListEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Health

GET/v1/healthz

Content-free liveness probe

Responses

200 — OK → object

Freshness

GET/v1/freshness/report

Live freshness aggregate over the documents visible to the caller

Parameters

Field	Type	Required	Description
`Braize-Version (header)`	string (date)	No	Override the workspace's pinned contract version.

Responses

200 — Freshness report scoped to the caller's ACL-visible documents → FreshnessReportEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

Memory

GET/v1/memory

Search this caller's own memories for one agent (isolated per agent+principal)

Parameters

Field	Type	Required	Description
`Braize-Version (header)`	string (date)	No	Override the workspace's pinned contract version.
`agent_id (query)`	string	Yes	Which agent's memory to search (the isolation boundary, with the caller's principal).
`conversation_id (query)`	string (uuid)	No	Narrow to one conversation's memories; omitted searches all of this agent's memories for the caller.
`q (query)`	string	No	Case-insensitive substring filter over memory content.
`limit (query)`	integer	No

Responses

200 — Active (non-invalidated) memories, newest first → AgentMemoryListEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

POST/v1/memory

Write one new agent memory (append-only; isolated per agent+principal)

Parameters

Field	Type	Required	Description
`Braize-Version (header)`	string (date)	No	Override the workspace's pinned contract version.

Request body: AppendMemoryRequest

Responses

201 — The written memory → AgentMemoryEnvelope
default — RFC 9457 Problem Details. `type` URIs are stable forever. → Problem

MCP tools

Tool and parameter names are permanent — new capabilities always arrive as new tools, so your integrations keep working.

search_knowledge

Permission-aware hybrid search over the workspace knowledge base. Returns ranked, cited PASSAGES (the data) so the calling agent synthesizes its own answer — no answer generation. Thin adapter over POST /v1/retrieve; ACL pre-filtered to the caller's principal. For a generated answer in a human channel, use the REST /v1/query surface instead.

Input

Field	Type	Required	Description
`text`	string	Yes	The search query in any supported language.
`top_k`	integer	No	Max passages to return (server caps).

Output

Field	Type	Required	Description
`passages`	array of object	Yes	Ranked, cited passages. Passage TEXT and provenance only — never embeddings.

get_document

Fetch the full detail of one document in the workspace by id — version history, parse status, freshness — permission-aware. Thin adapter over GET /v1/documents/{document_id}.

Input

Field	Type	Required	Description
`document_id`	string	No	Id of the document to fetch. Optional in the schema (additive); required at call time — a missing id is a tool error.

Output

Field	Type	Required	Description
`id`	string	No
`title`	string	No
`url`	string	No
`doc_class`	string	No
`parse_status`	string	No	pending \| ok \| failed \| quarantined — open string, tolerate unknown values.
`chunk_count`	integer	No
`freshness_score`	number	No
`versions`	array of object	No

list_sources

List the connectors / sources connected to the workspace with sync health and indexed-document counts. Thin adapter over GET /v1/sources.

Output

Field	Type	Required	Description
`sources`	array of object	No	Connected sources. Sync health + indexed-doc counts only.

get_freshness_report

Live freshness aggregate over the documents visible to the caller (bucket counts + the stalest documents) — permission-aware, ACL-scope-cohort only, never workspace-wide. Thin adapter over GET /v1/freshness/report.

Output

Field	Type	Required	Description
`as_of`	string	Yes
`scope`	string	Yes	public \| principal — open string, tolerate unknown values.
`visible_documents`	integer	Yes
`scored_documents`	integer	Yes
`mean_score`	number	No
`buckets`	array of object	Yes
`stale_documents`	array of object	Yes	The stalest scored documents, lowest score first.

Schemas

QueryRequest

Field	Type	Required	Description
`text`	string	Yes
`conversation_id`	string (uuid)	No
`channel_hint`	string	No
`stream`	boolean	No
`system_prompt`	string	No	Operator instructions appended to (never replacing) Braize's grounded system prompt. Grounding, citation, and numeric-fidelity rules always win.
`model`	string	No	Model alias to start generation with. Open string — values today: chat-default \| chat-strong \| chat-fast; new aliases are additive forever. Unknown aliases fail with 422 https://braize.app/errors/invalid-request. Braize may still escalate (complex route / refusal retry).
`temperature`	number	No	Sampling temperature for the answer generation call. Default 0.
`top_k`	integer	No	Max context chunks assembled for the answer (context_top_k). Default 12.
`answer_mode`	string	No	Speed/accuracy trade-off for this answer. Open string — recognized values today: fast \| balanced \| thorough; new modes are additive forever, and servers treat unknown values as the default (balanced). fast = quickest, more concise answer with lighter quality checks (no groundedness verdict fields, smaller context) — facts are still cited. balanced (default) = today's behavior, byte-identical. thorough = extra time for the most accurate answer: strongest starting model, larger context, extra retry budget, full groundedness checking. An explicit model/temperature/ top_k override beats the mode's preset for that knob. fast and thorough bypass the answer cache like other overrides; balanced alone stays cache-eligible (it IS the default).

QueryResponseEnvelope

Field	Type	Required	Description
`data`	Answer	Yes
`meta`	Meta	Yes

Meta

Field	Type	Required
`request_id`	string	Yes
`braize_version`	string (date)	Yes
`degraded`	boolean	No

Answer

Field	Type	Required	Description
`conversation_id`	string (uuid)	Yes
`confidence`	number	Yes
`blocks`	array of ContentBlock	Yes	Evidence/content blocks. Native `/v1/query` responses return citation/evidence blocks by default; generated prose (`type: text`) is included only when the workspace response setting `include_generated_answers` is enabled. Clients must still tolerate text blocks because they remain part of the additive content-block union and are used by opted-in workspaces.

ContentBlock

One of: TextBlock | CitationBlock

TextBlock

Field	Type	Required	Description
`type`	"text" (constant)	Yes
`text`	string	Yes

RetrieveRequest

Field	Type	Required	Description
`text`	string	Yes
`top_k`	integer	No	Max passages to return (after rerank). Default 25 (the agent surface has no generation cost, so it returns a wider set than the generated-answer context).

RetrieveResponseEnvelope

Field	Type	Required	Description
`data`	RetrieveResult	Yes
`meta`	Meta	Yes

RetrieveResult

Field	Type	Required	Description
`passages`	array of Passage	Yes

Passage

Field	Type	Required	Description
`text`	string	Yes
`score`	number	Yes	Relevance in [0,1] (normalized rerank score; higher = more relevant).
`document_id`	string (uuid)	Yes
`document_version`	string	No
`title`	string	Yes
`source_ref`	string	No	Source document reference (upload filename / connector ref).
`heading_path`	array of string	No	Ancestor headings locating the passage in its document.
`context_prefix`	string	No	Situating sentence the passage was indexed with (helps interpret it).

CitationBlock

Field	Type	Required
`type`	"citation" (constant)	Yes
`document_id`	string (uuid)	Yes
`document_version`	string	No
`title`	string	Yes
`url`	string (uri)	No
`excerpt`	string	No
`marker`	integer	No

Problem

Field	Type	Required
`type`	string (uri)	Yes
`title`	string	Yes
`status`	integer	Yes
`detail`	string	No
`instance`	string	No

SseStream

Server-Sent Events stream. Each event's `data:` payload conforms to the schema named by its `event:` field — answer.delta → SseAnswerDelta, answer.sources → SseAnswerSources, answer.citation → SseAnswerCitation, answer.done → SseAnswerDone, error → SseError.

SseAnswerDelta

Field	Type	Required	Description
`text`	string	Yes

SseAnswerCitation

Field	Type	Required	Description
`block`	CitationBlock	Yes
`anchor_offset`	integer	No

SseAnswerSources

Field	Type	Required	Description
`sources`	array of CitationBlock	Yes

SseAnswerDone

Field	Type	Required
`conversation_id`	string (uuid)	Yes
`confidence`	number	Yes
`grounded`	boolean	No
`groundedness`	number	No
`meta`	Meta	No

SseError

Field	Type	Required	Description
`problem`	Problem	Yes

UrlIngestRequest

Field	Type	Required	Description
`url`	string (uri)	Yes

IngestResult

Field	Type	Required
`document_id`	string (uuid)	Yes
`version_id`	string (uuid)	Yes
`chunks`	integer	Yes
`quarantined`	boolean	Yes

IngestResultEnvelope

Field	Type	Required	Description
`data`	IngestResult	Yes
`meta`	Meta	Yes

IngestPending

Field	Type	Required	Description
`document_id`	string (uuid)	Yes
`version_id`	string (uuid)	Yes
`status`	string	Yes	'pending' — poll GET /documents/{document_id} for parse_status

IngestPendingEnvelope

Field	Type	Required	Description
`data`	IngestPending	Yes
`meta`	Meta	Yes

DocumentSummary

Field	Type	Required	Description
`id`	string (uuid)	Yes
`title`	string	No
`filename`	object	No
`doc_class`	string	No
`parse_status`	string	No	pending \| ok \| failed \| quarantined ('pending' = async ingest in flight). Open string — clients MUST tolerate unknown values.
`chunk_count`	integer	Yes
`freshness_score`	number	No
`source_id`	object	No
`source_type`	object	No
`source_display_name`	object	No
`sync_status`	object	No	queued \| downloading \| processing \| indexed \| failed — the per-document sync lifecycle. Null for documents that predate the sync-status column (legacy rows). Open string — clients MUST tolerate unknown values.
`sync_error`	object	No
`byte_size`	object	No
`mime`	object	No
`updated_at`	object	No

DocumentList

Field	Type	Required
`documents`	array of DocumentSummary	Yes
`next_cursor`	object	No
`total`	object	No

DocumentListEnvelope

Field	Type	Required	Description
`data`	DocumentList	Yes
`meta`	Meta	Yes

DocumentVersion

Field	Type	Required
`id`	string (uuid)	Yes
`version`	integer	Yes
`byte_size`	integer	No
`mime`	string	No
`created_at`	string (date-time)	Yes
`purged_at`	string (date-time)	No

DocumentDetail

Field	Type	Required	Description
`id`	string (uuid)	Yes
`title`	string	No
`filename`	object	No
`url`	string (uri)	No
`doc_class`	string	No
`parse_status`	string	No	pending \| ok \| failed \| quarantined ('pending' = async ingest in flight). Open string — clients MUST tolerate unknown values.
`chunk_count`	integer	Yes
`freshness_score`	number	No
`source_id`	object	No
`source_type`	object	No
`source_display_name`	object	No
`sync_status`	object	No
`sync_error`	object	No
`byte_size`	object	No
`mime`	object	No
`updated_at`	object	No
`deleted_at`	string (date-time)	No
`versions`	array of DocumentVersion	Yes

DocumentDetailEnvelope

Field	Type	Required	Description
`data`	DocumentDetail	Yes
`meta`	Meta	Yes

DeleteResult

Field	Type	Required
`document_id`	string (uuid)	Yes
`deleted`	boolean	Yes
`purge_enqueued`	boolean	Yes

DeleteResultEnvelope

Field	Type	Required	Description
`data`	DeleteResult	Yes
`meta`	Meta	Yes

AppendMemoryRequest

Field	Type	Required	Description
`agent_id`	string	Yes	Which agent is writing this memory (part of the isolation boundary, with the caller's principal).
`content`	string	Yes
`conversation_id`	string (uuid)	No	Optional — scopes this memory to one conversation instead of the whole agent+principal.
`source_doc_ids`	array of string (uuid)	No	Provenance when this memory was derived from retrieved documents; empty for a purely agent-authored note.

AgentMemory

Field	Type	Required	Description
`id`	string (uuid)	Yes
`agent_id`	string	Yes
`conversation_id`	object	No
`content`	string	Yes
`source_doc_ids`	array of string (uuid)	No
`invalidated_at`	object	No	Set only once this memory has been superseded by a consolidation — never deleted.
`created_at`	string (date-time)	Yes

AgentMemoryEnvelope

Field	Type	Required	Description
`data`	AgentMemory	Yes
`meta`	Meta	Yes

AgentMemoryList

Field	Type	Required	Description
`memories`	array of AgentMemory	Yes

AgentMemoryListEnvelope

Field	Type	Required	Description
`data`	AgentMemoryList	Yes
`meta`	Meta	Yes

FreshnessBucket

Field	Type	Required	Description
`bucket`	string	Yes	fresh \| aging \| stale \| unknown — open string.
`count`	integer	Yes

DocumentFreshnessSummary

Field	Type	Required
`id`	string (uuid)	Yes
`title`	object	No
`doc_class`	object	No
`freshness_score`	object	No
`updated_at`	object	No

FreshnessReport

Field	Type	Required	Description
`as_of`	string (date-time)	Yes
`scope`	string	Yes	public \| principal — whether the caller asserted an end-user identity (X-Braize-Principal) or was resolved to the workspace-public group. Open string, tolerate unknown values.
`visible_documents`	integer	Yes	Count of documents ACL-visible to the caller (the report's cohort).
`scored_documents`	integer	Yes	Of visible_documents, how many have a computable freshness score.
`mean_score`	object	No
`buckets`	array of FreshnessBucket	Yes
`stale_documents`	array of DocumentFreshnessSummary	Yes	The stalest scored documents, lowest score first (top 10).

FreshnessReportEnvelope

Field	Type	Required	Description
`data`	FreshnessReport	Yes
`meta`	Meta	Yes

CreateSourceRequest

Field	Type	Required	Description
`connector_kind`	string	Yes	One of the known connector kinds (see GET /connectors catalog). Immortal — the kind is stored on the source row and flows through the sync engine; changing it after creation is not supported.
`display_name`	string	Yes	Human-readable name for this source (e.g. "Marketing Drive"). The user can rename it later; this is the wizard's default label.
`config`	object	No	Optional partial configuration (e.g. pre-selected root folder). Validated against the connector's config_schema; unknown keys are rejected. Safe to omit — the wizard populates it on Screen 2.

SourceDraft

Field	Type	Required	Description
`source_id`	string (uuid)	Yes	Durable ID for this source. Embedded in the OAuth state token so the callback can attach the credential to this exact draft. Also passed in wizard redirect URLs (?source_id=…) so the frontend can resume.
`state`	string	Yes	Current wizard lifecycle state. Always "draft" on creation. Immutable string values (additive-only; clients must-ignore unknown states): draft \| awaiting_credentials \| validating \| configuring \| ready \| active \| paused \| broken \| disconnecting \| archived
`wizard_cursor`	string	No	Key of the wizard step the user last reached (matches setup_steps_v2[].key). Null on creation; set by the callback and PATCH calls.

ActivateSourceResponse

Field	Type	Required	Description
`source_id`	string (uuid)	Yes	The activated source ID.
`state`	string	Yes	Always 'active' on success.

ActivateSourceResponseEnvelope

Field	Type	Required	Description
`data`	ActivateSourceResponse	Yes
`meta`	Meta	Yes

DisconnectSourceResponse

Field	Type	Required	Description
`source_id`	string (uuid)	Yes	The disconnected source ID.
`state`	string	Yes	Always 'archived' after a successful disconnect (idempotent).
`purge_enqueued`	boolean	Yes	True when the source's indexed content was enqueued for the RTBF purge cascade (documents soft-deleted + purge_log rows written). False only when the source had no content to purge (e.g. a never-synced draft).

DisconnectSourceResponseEnvelope

Field	Type	Required	Description
`data`	DisconnectSourceResponse	Yes
`meta`	Meta	Yes

SourceDraftEnvelope

Field	Type	Required	Description
`data`	SourceDraft	Yes
`meta`	Meta	Yes

SourceSummary

Field	Type	Required	Description
`id`	string (uuid)	Yes
`type`	string	Yes
`display_name`	string	Yes
`health`	string	Yes
`docs_indexed`	integer	No
`capabilities`	array of string	No
`acl_fidelity`	string	No
`setup_state`	string	No
`last_indexed_at`	string (date-time)	No
`failed_count`	integer	No
`sync_state`	object	No	Per-source sync progress: {"status":"syncing"} / {"status":"completed","upserted":N}
`sync_progress`	one of: SyncProgress \| null	No
`recent_runs`	object	No

SyncProgress

Field	Type	Required
`queued`	integer	Yes
`downloading`	integer	Yes
`processing`	integer	Yes
`indexed`	integer	Yes
`failed`	integer	Yes

SyncRunSummary

Field	Type	Required
`started_at`	string (date-time)	Yes
`finished_at`	string (date-time)	No
`mode`	string	Yes
`status`	string	Yes
`docs_upserted`	integer	No
`docs_deleted`	integer	No
`error`	object	No

SourceList

Field	Type	Required	Description
`sources`	array of SourceSummary	Yes

SourceSummaryEnvelope

Field	Type	Required	Description
`data`	SourceSummary	Yes
`meta`	Meta	Yes

TriggerSyncResponse

Field	Type	Required	Description
`source_id`	string (uuid)	Yes
`sync_requested`	boolean	Yes

TriggerSyncResponseEnvelope

Field	Type	Required	Description
`data`	TriggerSyncResponse	Yes
`meta`	Meta	Yes

SourceListEnvelope

Field	Type	Required	Description
`data`	SourceList	Yes
`meta`	Meta	Yes

SetupStepV2

One step in the connector wizard (framework §5.2). The `type` field is the immortal discriminator the wizard engine reads to decide which widget to render. Additional type-specific properties are added additively as OPTIONAL FLAT FIELDS on this same object (clients must-ignore unknown fields per api-design §4). CONSTRAINT: this schema is intentionally flat — never restructure to oneOf/ discriminatedUnion. Adding a oneOf branch removes the flat path, which is a breaking change for any client that already reads the flat fields.

Field	Type	Required	Description
`type`	string	Yes	Immortal step-type token (never renamed; new types added additively): authenticate.oauth_flow \| authenticate.enter_api_key \| authenticate.enter_basic \| authenticate.enter_token \| authenticate.enter_webhook_secret \| authenticate.none \| set_permissions \| configure_scope \| preview \| confirm
`title`	string	Yes	Human-readable step label the wizard renders in the progress bar.
`key`	string	Yes	Unique step identifier within this connector (wizard cursor / resume-from-step; never reused within a connector's step list).

ConnectorCatalogEntry

Field	Type	Required	Description
`kind`	string	Yes
`display_name`	string	Yes
`status`	string	Yes	live \| skeleton \| broken — honest wiring state
`auth`	string	Yes	none \| api_key \| oauth2
`capabilities`	array of string	Yes
`acl_fidelity`	string	Yes	connector ACL-fidelity ladder (PRD §5.8)
`min_plan`	string	Yes	cheapest plan that unlocks this connector
`webhook_capable`	boolean	No
`delete_detection`	boolean	No
`oauth_scopes`	array of string	No
`subprocessors`	array of string	No
`setup_steps`	array of string	No
`setup_steps_v2`	array of SetupStepV2	No

ConnectorCatalog

Field	Type	Required	Description
`connectors`	array of ConnectorCatalogEntry	Yes

ConnectorCatalogEnvelope

Field	Type	Required	Description
`data`	ConnectorCatalog	Yes
`meta`	Meta	Yes

RequestLog

Field	Type	Required	Description
`id`	string (uuid)	Yes
`request_id`	string (uuid)	Yes
`method`	string	Yes
`path`	string	Yes
`status_code`	integer	Yes
`duration_ms`	integer	Yes
`error_type`	object	No	RFC 9457 `type` URI of the failure (status_code >= 400 only)
`error_title`	object	No
`error_detail`	object	No
`created_at`	string (date-time)	Yes

RequestLogList

Field	Type	Required	Description
`requests`	array of RequestLog	Yes

RequestLogListEnvelope

Field	Type	Required	Description
`data`	RequestLogList	Yes
`meta`	Meta	Yes

ConversationMessage

Field	Type	Required
`role`	string	Yes
`content`	string	Yes
`created_at`	string (date-time)	Yes

ConversationHistory

Field	Type	Required	Description
`conversation_id`	string (uuid)	Yes
`messages`	array of ConversationMessage	Yes

ConversationHistoryEnvelope

Field	Type	Required	Description
`data`	ConversationHistory	Yes
`meta`	Meta	Yes

ChatMessage

Field	Type	Required	Description
`role`	string	Yes
`content`	string	Yes

ChatCompletionRequest

Field	Type	Required	Description
`model`	string	Yes	Braize model alias (chat-default \| chat-strong \| chat-fast; new aliases additive forever). Unknown values fail with an OpenAI-shaped 404 model_not_found error.
`messages`	array of ChatMessage	Yes
`temperature`	number	No
`stream`	boolean	No
`answer_mode`	string	No	ADDITIVE Braize extension (standard OpenAI SDKs may pass it via extra_body): the same speed/accuracy trade-off as QueryRequest's answer_mode — fast \| balanced \| thorough, open string, unknown values treated as balanced. Mapped through to the shared query pipeline; the explicit `model`/`temperature` fields of this request beat the mode's presets for those knobs.

ChatCompletionChoice

Field	Type	Required
`index`	integer	Yes
`message`	ChatMessage	Yes
`finish_reason`	object	Yes

ChatCompletionUsage

Token counts estimated with the pipeline's token counter over the request messages and the answer text — an estimate, not vendor billing.

Field	Type	Required
`prompt_tokens`	integer	Yes
`completion_tokens`	integer	Yes
`total_tokens`	integer	Yes

ChatCompletionResponse

Field	Type	Required
`id`	string	Yes
`object`	string	Yes
`created`	integer	Yes
`model`	string	Yes
`choices`	array of ChatCompletionChoice	Yes
`usage`	ChatCompletionUsage	No
`braize`	BraizeChatExtension	No

ChatCompletionDelta

Field	Type	Required	Description
`role`	string	No
`content`	string	No

ChatCompletionChunkChoice

Field	Type	Required
`index`	integer	Yes
`delta`	ChatCompletionDelta	Yes
`finish_reason`	object	No

ChatCompletionChunk

Field	Type	Required
`id`	string	Yes
`object`	string	Yes
`created`	integer	Yes
`model`	string	Yes
`choices`	array of ChatCompletionChunkChoice	Yes
`usage`	ChatCompletionUsage	No
`braize`	BraizeChatExtension	No

BraizeChatExtension

Braize vendor extension on chat completions: grounding verdict and the existing CitationBlock citations (one transformer, two surfaces). A KB miss is NOT an error — content carries the fallback message with finish_reason "stop", is_fallback true, and empty citations. A mid-stream failure surfaces as `error` (a stable RFC 9457 Problem object) on the final chunk, then `data: [DONE]`.

Field	Type	Required
`conversation_id`	string (uuid)	No
`grounded`	boolean	No
`groundedness`	number	No
`confidence`	number	No
`is_fallback`	boolean	No
`citations`	array of CitationBlock	No
`error`	Problem	No

ChatCompletionErrorDetail

Field	Type	Required
`message`	string	Yes
`type`	string	Yes
`code`	object	No
`param`	object	No

ChatCompletionError

Field	Type	Required	Description
`error`	ChatCompletionErrorDetail	Yes

API & MCP reference

REST API

Ask questions

Agent-native retrieval

OpenAI-compatible

Documents

Sources & connectors

Conversations

Request log

Health

Freshness

Memory

MCP tools

Schemas

On this page