Pick one from a list

post/choice

Selects the best option from your choices list. Returns the chosen label, P(choice), and the full distribution over all options.

At least 2 choices are required. More than 26 is rejected (422).

Body ParametersExpand Collapse

choices: array of unknown

The options to choose from (2–26 items).

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"

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.

Pick one from a list

curl https://api.articul8.ai/bivia/choice \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "choices": [
            "billing",
            "refunds",
            "technical"
          ],
          "question": "Which team handles this?"
        }'

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "decide",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "distribution": {
    "foo": 0
  },
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "probability": 0,
  "think_allowed": true
}

Returns Examples

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "decide",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "distribution": {
    "foo": 0
  },
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "probability": 0,
  "think_allowed": true
}