Bivia API

Bivia is a multimodal decision model that reads text, images, documents, audio, and signals, then hands you one calibrated decision.

Quickstart Make your first call in under a minute.

API Reference Every decision endpoint.

LLMs generate. Bivia decides.

Agents call a large language model for every small, uncertain moment: is this urgent, which team owns this ticket, how risky is this step. Each call burns hundreds of tokens to reach “yes”, “option B”, or “3.7 out of 5”, and your code still has to parse the reply.

Bivia answers those moments directly, in one pass, with a structured response your code can use as is.

Bivia

{
  "type": "choice",
  "value": "Infra",
  "probability": 0.94,
  "distribution": { "Infra": 0.94, "Billing": 0.04, "Growth": 0.02 },
  "status": "answered"
}

A typical LLM

Great question! Looking at this ticket, the 502 errors right after the deploy
suggest an infrastructure issue. That said, checkout is affected, so Billing
may want to take a look too. On balance, I'd lean towards Infra, although it's
hard to be certain without more context...

Bivia doesn’t replace your LLM. Use your LLM to write and plan, and Bivia for the bounded decisions around it.

How it works

Send the context (state), the question, and the shape of answer you want. Get back a typed decision.

curl -s https://api.articul8.ai/bivia/choice \
  -H "Authorization: Bearer $A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Ticket: 502 errors on checkout right after the 2pm deploy.",
    "question": "Which team owns this ticket?",
    "choices": ["Infra", "Billing", "Growth"]
  }'

Every response has the same core fields:

• type: the kind of answer (boolean, choice, score, …)
• value: the answer itself
• status: answered, or abstained when Bivia isn’t sure
• probability and distribution: how confident Bivia is in each option

What you can ask

Endpoint	Answers with
POST /decide	Whichever type fits the question
POST /boolean	Yes or no
POST /choice	One option from a list
POST /score	A number on a scale
POST /set	Every option that applies
POST /span	Quoted text ranges from the input
POST /extract	Exact field values copied from a document
POST /ground	Boxes in an image, or moments in a video
POST /ds	A decision over raw numeric signals
POST /v1/systemone	Many typed answers over one context

See Decision Types for examples of each.

Fast by default. Deep when it matters.

Set the mode on each request, and let Bivia abstain when it isn’t sure.

Fast

mode: "fast" (default). One decision in a single pass, near-instant. Built for high-volume calls like routing and triage. Set think: false for the lowest latency.

Deep

mode: "deep". Decides, then challenges its own decision before committing. If it’s still unresolved, it abstains.

Abstain

allow_abstain: true (default). If the evidence is missing or conflicting, Bivia returns abstained with the reason instead of guessing. See Abstention.

Calibrated

A confidence of 0.9 means Bivia is right about 9 times out of 10, so you can set thresholds you trust.

Works with what you have

Attach any mix of inputs to a request. Bivia considers all of them together. See Multimodal Inputs.

Text and documents

Plain text in state, plus PDF, DOCX, PPTX, XLSX, CSV, HTML, Markdown, and source code.

Images and video

Screenshots, scans, photos, and charts. Video clips on /ground.

Audio

Speech and audio clips, such as support calls.

Signals

Raw numeric series, such as sensor or telemetry data, on /ds.

Where it fits

Every complex workflow breaks down into small, typed judgments. Teams use Bivia for:

• Agent guardrails: score a tool call’s risk before it runs, pick the next step, or check whether the agent is really done.
• Documents and compliance: classify pages, check an LLM’s table extraction against the source, and quote the exact sentence that supports an answer.
• Industrial and energy: turn sensor arrays, equipment photos, and grid alarms into an operator action.
• Manufacturing: read wafer maps, metrology, and engineer notes, and hand structured judgments to a scheduler.
• Optimization: pick the next move or algorithm inside a solver loop, or decide when to stop.

Install an SDK

pip install bivia                     # Python
npm install @articul8/bivia           # Node.js
go get github.com/articul8/bivia-go   # Go
cargo add bivia                       # Rust

Quickstart Set your API key and make a first call.

Decision Types Examples of every kind of answer.