Multiple typed questions in one request

post/v1/systemone

Send one context (state, plus optional images/documents/signals) and many named questions. Each question is independently typed and answered.

Question types: boolean (or noul / bool), choice, score, set, box (visual grounding). Unknown types are rejected (422).

Defaults: fast mode, no thinking, no abstention. Set mode: "deep" to enable abstention (abstained: true is then possible on individual answers).

Each question is metered independently; usage.billable_tokens is the sum of per-question minimums.

Body ParametersExpand Collapse

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

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 }

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.

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

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"

model: optional string

Accepted for compatibility. The response model is always dec-1.

questions: optional map[object { buckets, criteria, instructions, 4 more } ]

Map of question name → typed question definition.

buckets: optional number

Score bucket count when levels is not provided.

minimum2

criteria: optional map[string] or array of unknown

Choice options. An object maps option key → description; a list of names is also accepted.

Accepts one of the following:

UnionMember0 = map[string]

UnionMember1 = array of unknown

instructions: optional string

The question text.

levels: optional array of unknown

Score bucket labels. Must be a list when present; a non-list type is rejected (422). Array length sets the bucket count.

options: optional array of unknown

Choice names (used when criteria is empty).

question: optional string

Alternative to instructions.

type: optional string

boolean (or noul / bool), choice, score, set, box. Unknown types are rejected (422). Defaults to choice when omitted.

signals: optional array of object { data, channels, dtype, 2 more }

data: unknown

Signal data as [channels][timesteps] (list of lists). Each inner list is one channel of samples.

channels: optional number

Number of channels (required when data is a base64 buffer).

dtype: optional string

Data type when data is a base64 buffer.

fs: optional number

Sample rate in Hz.

name: optional string

Human-readable name for the signal.

state: optional string

ReturnsExpand Collapse

BatchResponse = object { answers, model, usage }

answers: map[object { abstained, choice, type, 2 more } or object { abstained, type, confidence, 2 more } or object { abstained, score, type, 4 more } or 2 more]

Answers keyed by the question names from the request.

Accepts one of the following:

BatchChoiceAnswer = object { abstained, choice, type, 2 more }

abstained: boolean

choice: unknown

type: "choice"

Accepts one of the following:

"choice"

confidence: optional number

P(choice). Null when abstained.

probabilities: optional map[number]

BatchBooleanAnswer = object { abstained, type, confidence, 2 more }

abstained: boolean

type: "noul"

Accepts one of the following:

"noul"

confidence: optional number

noul: optional number

P(yes) in [0, 1].

probability: optional number

Same as noul — P(yes).

BatchScoreAnswer = object { abstained, score, type, 4 more }

abstained: boolean

score: number

Expected value on [0, 1]. Null when abstained.

type: "score"

Accepts one of the following:

"score"

confidence: optional number

distribution: optional map[number]

legend: optional map[string]

Index → label mapping from the criteria array.

probabilities: optional map[number]

BatchSetAnswer = object { abstained, selected, type, probabilities }

abstained: boolean

selected: array of unknown

Options selected (probability ≥ 0.5).

type: "set"

Accepts one of the following:

"set"

probabilities: optional map[number]

BatchBoxAnswer = object { abstained, type, box, 2 more }

abstained: boolean

type: "box"

Accepts one of the following:

"box"

box: optional object { bottom, left, right, top }

Normalized [0, 1] bounding box. Null when abstained.

bottom: optional number

left: optional number

right: optional number

top: optional number

confidence: optional number

label: optional string

model: "dec-1"

Accepts one of the following:

"dec-1"

usage: object { billable_tokens, input_tokens, questions, output_tokens }

billable_tokens: number

Sum of per-question billing token minimums.

input_tokens: number

Sum of per-question input tokens.

questions: number

Number of questions in the batch request.

output_tokens: optional number

Typically 0 for decision readouts.

Multiple typed questions in one request

curl https://api.articul8.ai/bivia/v1/systemone \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{}'

{
  "answers": {
    "foo": {
      "abstained": true,
      "choice": {},
      "type": "choice",
      "confidence": 0,
      "probabilities": {
        "foo": 0
      }
    }
  },
  "model": "dec-1",
  "usage": {
    "billable_tokens": 0,
    "input_tokens": 0,
    "questions": 0,
    "output_tokens": 0
  }
}

Returns Examples

{
  "answers": {
    "foo": {
      "abstained": true,
      "choice": {},
      "type": "choice",
      "confidence": 0,
      "probabilities": {
        "foo": 0
      }
    }
  },
  "model": "dec-1",
  "usage": {
    "billable_tokens": 0,
    "input_tokens": 0,
    "questions": 0,
    "output_tokens": 0
  }
}