AI assistant API

What it doesCopy Anchor Link

The assistant API runs the same AI assistant as the Brivio app, over the public API: you open a thread, send a message and get the answer, as JSON or streamed with Server-Sent Events. It reads the organization's data with the permissions of the person behind your credential.

The assistant never changes anything on its own. When it wants to create or modify something, the change becomes a proposal that the person approves in the Brivio app, in the Approval Feed. Approval is not possible over the API, from any credential. You can list pending proposals and reject them.

Credentials and scopesCopy Anchor Link

• An OAuth access token acts for the user who granted it.
• An API key acts for the member who created it. If that person leaves the organization, the key stops working for the assistant on the next request.
• Scopes: assistant:read (threads, proposals) and assistant:write (run a turn, open a thread, reject a proposal). Every turn uses AI credit from the organization's wallet and counts against its AI budgets.

EndpointsCopy Anchor Link

Thread and proposal ids are positive integers. A thread that is not yours is a 404.

WebhooksCopy Anchor Link

Subscribe a webhook to assistant.proposal.created and assistant.proposal.resolved to learn when a turn leaves a proposal and when it is approved, fails, is rejected or expires — without polling. Payloads carry ids, the tool name and approve_url, never the tool input. See Webhooks.

Running a turnCopy Anchor Link

curl -X POST https://api.brivio.ro/v1/assistant/threads/42/runs \
  -H "Authorization: Bearer $BRIVIO_KEY" -H "Content-Type: application/json" \
  -d '{"message":"How many invoices are overdue?","locale":"en"}'

The response data has text, status (completed, pending_approval or refused), pending_approvals (each with approve_url) and usage. Every response carries X-Brivio-AI: generated; reviewed=none; model=codai: the text is AI-generated and not reviewed by a person.

StreamingCopy Anchor Link

Send "stream": true (or Accept: text/event-stream) and read events: text with { "delta": "…" }, then done with the full run, or error. Budget, rate-limit and validation errors arrive before the stream opens, as normal JSON (402, 422, 429).

SDKs, CLI, MCPCopy Anchor Link

• TypeScript: brivio.assistant.runs.create(...) / brivio.assistant.runs.stream(...).
• PHP: createAssistantRun($threadId, ['message' => '…']) (JSON only).
• CLI: brivio assistant ask "How many invoices are overdue?" (streams by default).
• MCP: the brivio_ask_assistant tool, for Claude, ChatGPT or any MCP client — also on the read-only hosted server, because a turn only proposes changes. Setup: Brivio in Claude and ChatGPT.

Custom HTTP toolsCopy Anchor Link

An administrator can connect your own API as an assistant tool in Assistant → Tools (permission assistant.extend). Every call needs the user's approval in the chat, HTTPS public hosts only, and the secret is injected server-side as {{secret}} in a header.

The optional input JSON Schema becomes the tool's typed input. It must have an object root and may use string (with enum, maxLength), number / integer (with minimum, maximum), boolean, nested object (with properties, required) and array (with an items schema and maxItems). Limits: 4 nesting levels, 50 properties per object, 100 items per array, 200 nodes. $ref, oneOf / anyOf, additionalProperties, pattern and format are not supported; an unsupported schema is refused when you save it, with the path that failed.

Your endpoint receives only the keys the schema declares, at every level: anything else the model adds is dropped and listed in the result as droppedArguments (for example lines[0].notes). POST, PUT and PATCH send JSON; GET sends a query string, with nested values JSON-encoded.

Fiscal data and the AI providerCopy Anchor Link

From the moment the assistant reads fiscal or financial data (payroll, trial balance, P&L, banking, VAT, filings, SPV messages, receivables, contracts and the other reads that need a permission beyond membership), the rest of the conversation runs incognito at codai: no session memory is read or written, and message content is not kept for memory or data collection; only the call's billing data (tokens, cost) remains. This applies on the web, Telegram, email and the API, and stays on for every later message of the same conversation. The cost is a slightly slower first token, because the session is no longer reused.