Auto-detect decision type

post/decide

Analyzes the question and automatically selects the best decision type (boolean, choice, score, etc.) and extracts options when applicable.

Use this when you don't know the answer type in advance. The response type field tells you which type was selected.

Provide outcomes to constrain the options; otherwise the model infers them from the question text. At least 2 outcomes are required when provided. More than 26 is rejected (422).

Body ParametersExpand Collapse

question: string

The question to decide.

allow_abstain: optional boolean

When true (default), the model may abstain if it lacks confidence. When false, abstention is replaced by the best-effort answer.

audio: optional array of object { b64, mime, url }

Optional audio clips to include as context.

b64: optional string

Base64-encoded audio bytes.

mime: optional string

MIME type for b64 content.

url: optional string

Public HTTP(S) audio URL.

documents: optional array of object { b64, filename, mime, url }

Optional documents to include as context.

b64: optional string

Base64-encoded file bytes.

filename: optional string

Helps format detection (e.g., memo.txt, contract.pdf).

mime: optional string

MIME type of the document.

url: optional string

Public HTTP(S) URL to fetch the document from.

domain: optional string

Optional domain hint for specialized few-shot behavior (e.g., finance).

images: optional array of object { b64, mime, url }

Optional images to include as context.

b64: optional string

Base64-encoded image bytes (raw base64, not a data: URL). Pair with mime.

mime: optional string

MIME type for b64 content. Must be an image/* type.

url: optional string

Public HTTP(S) image URL. The server fetches it within a shared 60-second budget.

mode: optional "fast" or "deep"

fast — single-pass inference (lowest latency, default). deep — adds a verification step for higher confidence on hard questions. Any other value is rejected (422).

Accepts one of the following:

"fast"

"deep"

outcomes: optional array of unknown

Candidate outcomes (2–26 items). When omitted, the model infers options from the question text.

state: optional string

Text context for the decision. May be empty when images or documents carry the context.

think: optional boolean

Whether to allow a reasoning trace before deciding. Only honored in fast mode; ignored for deep. Set to false for lowest latency.

ReturnsExpand Collapse

CategoricalDecision = object { evidence, latency_ms, mode, 16 more }

evidence: object { spans }

spans: optional array of object { end, start, text }

Character ranges in the input text that support the decision.

end: number

Exclusive character offset.

start: number

Inclusive character offset into the state text.

text: string

The quoted substring.

latency_ms: number

Server-side processing time in milliseconds.

mode: "fast" or "deep"

Accepts one of the following:

"fast"

"deep"

model: string

The model that produced this decision.

status: "answered" or "abstained"

answered — the model produced a confident answer. abstained — the model was not confident enough; value is null.

Accepts one of the following:

"answered"

"abstained"

thought: boolean

Whether a reasoning trace was actually generated.

type: "decide" or "choice" or "boolean"

Accepts one of the following:

"decide"

"choice"

"boolean"

value: unknown

verification: object { performed, result }

performed: boolean

Whether the verification step ran (only in deep mode).

result: "passed" or "conflict" or "insufficient" or "not_applicable"

passed — verification confirmed the answer. conflict — verification disagreed (triggers abstention in deep mode). insufficient — not enough evidence to verify. not_applicable — verification was not performed (fast mode).

Accepts one of the following:

"passed"

"conflict"

"insufficient"

"not_applicable"

abstain_reason: optional "low_confidence" or "readout_disagreement" or "insufficient_evidence" or "unresolved_after_thinking"

Why the model abstained. null when status is answered.

low_confidence — probability mass was too spread out.
readout_disagreement — deep verification found a conflict.
insufficient_evidence — not enough context to decide.
unresolved_after_thinking — reasoning did not resolve ambiguity.

Accepts one of the following:

"low_confidence"

"readout_disagreement"

"insufficient_evidence"

"unresolved_after_thinking"

billable_tokens: optional number

Billing token count = max(1000, input_tokens). This is the number used for usage metering, with a per-decision floor of 1,000 tokens.

distribution: optional map[number]

Probability of each label, summing to 1. Present even on abstention. For boolean decisions, keys are yes and no.

document_notes: optional array of object { document, status, chars, 3 more }

Per-document extraction status. Present when documents were sent.

document: string

Filename or URL of the document.

status: "included" or "truncated" or "skipped"

Accepts one of the following:

"included"

"truncated"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was truncated or skipped.

tokens: optional number

truncated: optional boolean

document_tokens: optional number

Document-specific subset of input_tokens. Present when documents were sent.

grounded: optional boolean

true when the answer is grounded in the provided context (a direct readout). false when the answer is free-form generation.

image_tokens: optional number

Image-specific subset of input_tokens.

input_tokens: optional number

Total tokens processed (text + images + documents + audio).

probability: optional number

P(value). Omitted when the model abstains.

think_allowed: optional boolean

Whether thinking was allowed for this call. Only present in fast mode.

Auto-detect decision type

curl https://api.articul8.ai/bivia/decide \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "question": "Most likely diagnosis?"
        }'

{
  "type": "decide",
  "value": "pneumonia",
  "probability": 0.99,
  "distribution": {
    "common cold": 0.01,
    "pneumonia": 0.99,
    "healthy": 0
  },
  "status": "answered",
  "abstain_reason": null,
  "mode": "fast",
  "think_allowed": false,
  "thought": false,
  "grounded": true,
  "verification": {
    "performed": false,
    "result": "not_applicable"
  },
  "evidence": {
    "spans": []
  },
  "latency_ms": 110,
  "model": "dec-1",
  "input_tokens": 380,
  "billable_tokens": 1000
}

Returns Examples

{
  "type": "decide",
  "value": "pneumonia",
  "probability": 0.99,
  "distribution": {
    "common cold": 0.01,
    "pneumonia": 0.99,
    "healthy": 0
  },
  "status": "answered",
  "abstain_reason": null,
  "mode": "fast",
  "think_allowed": false,
  "thought": false,
  "grounded": true,
  "verification": {
    "performed": false,
    "result": "not_applicable"
  },
  "evidence": {
    "spans": []
  },
  "latency_ms": 110,
  "model": "dec-1",
  "input_tokens": 380,
  "billable_tokens": 1000
}