Quickstart

Quickstart

1. Get an API key

Sign up at articul8.ai and create an API key.

2. Make a decision

curl

curl -s https://api.articul8.ai/bivia/boolean \
  -H "Authorization: Bearer $A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "I was double-charged and support never replied.",
    "question": "Is this urgent?"
  }'

Python

from bivia import Bivia

client = Bivia(api_key="your-key")

result = client.decisions.boolean(
    state="I was double-charged and support never replied.",
    question="Is this urgent?",
)
print(result.value, result.probability)
# "yes" 0.88

Node.js

import Bivia from '@articul8/bivia';

const client = new Bivia({ apiKey: 'your-key' });

const result = await client.decisions.boolean({
  state: 'I was double-charged and support never replied.',
  question: 'Is this urgent?',
});
console.log(result.value, result.probability);
// "yes" 0.88

3. Try different decision types

Choice — pick one from a list

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

Score — numeric on a scale

curl -s https://api.articul8.ai/bivia/score \
  -H "Authorization: Bearer $A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer threatened to cancel today.",
    "question": "How urgent? (0=none, 1=critical)",
    "range": [0, 1],
    "buckets": 11
  }'

Batch — multiple questions at once

curl -s https://api.articul8.ai/bivia/v1/systemone \
  -H "Authorization: Bearer $A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "I was double-charged and support never replied.",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team?",
        "criteria": {"billing": "Disputes", "tech": "Defects"}
      },
      "urgent": {
        "type": "boolean",
        "instructions": "Is this urgent?"
      }
    }
  }'

4. Modes

Every decision endpoint accepts a mode parameter:

• fast (default) — single-pass, lowest latency
• deep — adds verification for higher confidence on hard questions

{ "question": "...", "mode": "deep" }

5. Abstention

By default, Bivia abstains when it’s not confident:

{
  "status": "abstained",
  "value": null,
  "abstain_reason": "low_confidence",
  "distribution": { "yes": 0.52, "no": 0.48 }
}

Set "allow_abstain": false to force a best-effort answer instead.