API Reference

Decisions

Turn shared context into typed answers: choose a category, score urgency, or estimate whether a condition is true.

Overview

Send the content to evaluate in state and your questions in questions; each answer comes back under its question ID. Two endpoints serve the same Decisions services with the decisions token scope. Omit service_id to use your default service (see Services). Each request returns one JSON response; streaming is not supported.

Choose an endpoint

/v1/decisions/v1/systemone

Services: /v1/decisions:Any decision service, including OpenAI, Anthropic and Google models.; /v1/systemone:System One (such as Clef) and TypeSafe only.
Question types: /v1/decisions:choice, score, boolean; /v1/systemone:choice, score, noul
Score levels: /v1/decisions:2–128; /v1/systemone:1–128
Distributions: /v1/decisions:When the service provides them; require_probabilities enforces it.; /v1/systemone:Always, plus per-answer confidence and a score legend.
Model: /v1/decisions:The service’s configured model.; /v1/systemone:Self-hosted System One also accepts a per-request model.
Response: /v1/decisions:Normalised AI SDK format.; /v1/systemone:Native System One format, unchanged.

Use /v1/decisions unless you already integrate with System One or TypeSafe.

Use the AI SDK

With AI SDK 7 and @inferada-ai/ai-sdk-provider 0.3, a decision model calls /v1/decisions. The API is experimental; pin the versions you test.

typescript

import { experimental_decide as decide } from 'ai'
import { createInferada } from '@inferada-ai/ai-sdk-provider'

const inferada = createInferada({ apiKey: process.env.INFERADA_API_KEY })
const result = await decide({
  model: inferada.decisionModel({ requireProbabilities: true }),
  state: 'Checkout returns a 503 for every customer.',
  questions: {
    team: {
      type: 'choice',
      instructions: 'Which team should handle this ticket?',
      criteria: { billing: 'Invoices and charges', reliability: 'Service outages' }
    },
    outage: { type: 'boolean', instructions: 'Does this describe an outage?' }
  },
  maxRetries: 0
})

console.log(result.answers.team.choice)
console.log(result.answers.outage.probability)

Pass decisionModel({ serviceId }) to select a service. Inferada handles configured fallback, so the example disables SDK retries.

Make a decision

POST/v1/decisions

Scopedecisions

Evaluate one or more questions against the same state.

Request

staterequiredstring | object | array: Text or JSON shared by all questions.
questionsrequiredobject: 1–64 question IDs mapped to question objects.
questions.*.typerequiredchoice | score | boolean: choice picks a named option, score rates ordered levels, boolean estimates the probability that a condition is true.
questions.*.instructionsstring | object | array: What to decide.
questions.*.criteriaobject | array: choice: up to 512 named options. score: 2–128 ordered levels. boolean: optional true/false descriptions.
require_probabilitiesboolean: Reject the request if the service cannot return full choice and score distributions.
service_idstring: Optional service override. Omit to use your default.
modelstring: Optional; must match the service’s model.

bash

curl https://api.inferada.com/v1/decisions \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Every checkout attempt returns a 503. All our customers are blocked.",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": { "billing": "Invoices and charges", "reliability": "Service failures" }
      },
      "outage": { "type": "boolean", "instructions": "Does this describe an outage?" },
      "urgency": {
        "type": "score",
        "instructions": "How urgently should support respond?",
        "criteria": ["Routine request", "Some users blocked", "All users blocked"]
      }
    }
  }'

Response · 200

json

{
  "model": "clef",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "reliability",
      "probabilities": { "billing": 0.03, "reliability": 0.97 }
    },
    "outage": { "type": "boolean", "probability": 0.96 },
    "urgency": {
      "type": "score",
      "score": 1.91,
      "probabilities": { "0": 0.02, "1": 0.05, "2": 0.93 }
    }
  },
  "usage": { "input_tokens": 172, "output_tokens": 0 },
  "rounding": { "probability_decimals": 4, "score_decimals": 4 },
  "provider_metadata": { "inferada": { "confidence": { "team": 0.97, "urgency": 0.93 } } },
  "warnings": []
}

answers.<id>object: choice: choice and probabilities. score: score, a value from 0 to the last level index, and probabilities. boolean: probability. Language-model services omit probabilities.
usageobject: input_tokens and output_tokens the request is billed on.
rounding, provider_metadata, warningsobject | array: Value precision, per-question confidence in inferada.confidence, and provider warnings, when the service supplies them.

Use the native System One format

POST/v1/systemone

Scopedecisions

The same request in the native System One format, for System One and TypeSafe services.

Request

state, questions and service_id work as for /v1/decisions; require_probabilities is not accepted. These fields differ:

questions.*.typerequiredchoice | score | noul: noul replaces boolean.
questions.*.criteriaobject | array: score accepts 1–128 levels; noul takes only true and false. Instructions and descriptions can be any JSON.
modelstring: Self-hosted System One services accept any model their upstream serves; other services require their configured model.

Response · 200

json

{
  "model": "clef",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "reliability",
      "confidence": 0.97,
      "probabilities": { "billing": 0.03, "reliability": 0.97 }
    },
    "outage": { "type": "noul", "noul": 0.96 },
    "urgency": {
      "type": "score",
      "score": 1.91,
      "confidence": 0.93,
      "legend": { "0": "Routine request", "1": "Some users blocked", "2": "All users blocked" },
      "probabilities": { "0": 0.02, "1": 0.05, "2": 0.93 }
    }
  },
  "usage": { "input_tokens": 172, "output_tokens": 0 }
}

answers.<id>object: As for /v1/decisions, except noul for true/false. choice and score always include probabilities, confidence when supplied, and a legend for scores.
usageobject: input_tokens and output_tokens the request is billed on.

Limits and errors

A request takes up to 64 questions and 512 options, where each true/false question counts as two. TypeSafe services accept at most 255 choices and 10 score levels. Service context and body-size limits, and your rate limits, also apply. Both endpoints use your service’s usage pricing; failed requests are not charged, except rejected answers below.

400 / 413 / 422validation: Invalid JSON, unknown fields, invalid questions, a model the service does not allow, or a service the endpoint does not support. Upstream validation errors keep their status.
422 decision_answer_rejectedanswer: /v1/decisions on a language-model service returned an answer outside your questions. Charged when the provider reported usage; retrying usually repeats it.
401 / 403authentication: Missing or invalid token, or missing decisions scope.
404routing: No active service matches the request.
429limits: An Inferada or upstream limit was reached. Retry-After is forwarded.
502 / 503 / 504 / 529upstream: Upstream failure or invalid answer, unavailable service, timeout, or overload.