Multi-select from a list

post/set

Independent yes/no probability per option (not a distribution that sums to 1). value contains every option whose probability is at least 0.5, in request order. The probabilities map shows the independent P(applies) for each option.

Audio is accepted only on deployments that transcribe speech; otherwise a request with audio returns 503.

Body ParametersExpand Collapse

options: array of string

The options to select from (zero or more may be selected).

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

SetDecision = object { evidence, latency_ms, mode, 14 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" or "audio"

The mode that ran. audio is reported when an audio clip was decided directly; it cannot be sent as a request mode.

Accepts one of the following:

"fast"

"deep"

"audio"

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: "set"

Accepts one of the following:

"set"

value: unknown

Options with probability ≥ 0.5, in request order.

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.

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, or (remaining) for documents that were never read because the context limit was already reached.

status: "included" or "skipped"

Accepts one of the following:

"included"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was skipped.

tokens: optional number

truncated: optional boolean

Present and true on an included document whose text was cut to fit the context limit (about 48,000 characters).

document_tokens: optional number

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

image_tokens: optional number

Image-specific subset of input_tokens.

input_tokens: optional number

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

probabilities: optional map[number]

Independent P(option applies) for each option. Does not sum to 1.

think_allowed: optional boolean

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

Multi-select from a list

curl https://api.articul8.ai/bivia/set \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "options": [
            "cancel",
            "refund",
            "status"
          ],
          "question": "Which actions apply?"
        }'

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "set",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "probabilities": {
    "foo": 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": "set",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "probabilities": {
    "foo": 0
  },
  "think_allowed": true
}