Numeric score on a scale

post/score

Returns the expected value on a numeric scale defined by range (default [0, 1]), divided into buckets evenly spaced levels (default 11). The levels object shows the probability mass at each level.

There is no single probability field for scores; instead, the full distribution is in levels. buckets must be at least 2.

If the question text does not already name both range endpoints, the server appends "Answer on a numeric scale from {lo} to {hi}." so the model sees the scale.

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.

buckets: optional number

Number of evenly spaced levels on the scale.

minimum2

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"

range: optional array of number

Inclusive [low, high] of the numeric scale.

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

ScoreDecision = object { evidence, latency_ms, mode, 15 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: "score"

Accepts one of the following:

"score"

value: unknown

Expected value on the requested range. Null when abstained.

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.

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).

levels: optional map[number]

Per-level probability. Keys are formatted level values (e.g., "0", "0.1", "1").

think_allowed: optional boolean

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

Numeric score on a scale

curl https://api.articul8.ai/bivia/score \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "question": "How urgent is this (0=none, 1=critical)?"
        }'

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "score",
  "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,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "levels": {
    "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": "score",
  "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,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "levels": {
    "foo": 0
  },
  "think_allowed": true
}