arbiro/DocsBack to site ↗
Browse documentation
Documentation  /  API reference

Create a decision

Send caller-defined state and named questions through one model or a pinned policy.

POST/v1/decide
state · requiredString, object or array containing the input. Other root scalars are rejected.
questions · requiredNonempty map of up to 100 named questions. Every question needs a type and nonempty instructions.
policy / modelSelect one, not both. Omit both to use the active policy. Example pinned policy: default-cascade@v1.
external_idOptional correlation string (up to 200 characters). It is not a retry key.
idempotency_keyOptional retry key (1–200 characters), scoped to tenant and route. Prefer the Idempotency-Key header.

Question types

choicecriteria maps at least two stable option IDs to descriptions. The answer names the selected option.
scorecriteria is an ordered list of at least two descriptions. The numeric answer is on the 0 to length−1 scale.
noulBinary proposition. The answer’s noul value is a probability from 0 to 1, not a yes/no string.

Request

JSON
{
  "policy": "default-cascade@v1",
  "state": {
    "message": "The delivery window moved to Friday."
  },
  "questions": {
    "topic": {
      "type": "choice",
      "instructions": "Classify the message.",
      "criteria": {
        "schedule": "Timing or dates",
        "other": "Any other subject"
      }
    },
    "mentions_date": {
      "type": "noul",
      "instructions": "Does the text mention a day or date?"
    }
  }
}

Response

HTTP 200 · response excerpt
{
  "status": "completed",
  "branch": "answer_o",
  "model": "decisions-staging-v1",
  "answers": {
    "topic": {
      "type": "choice",
      "choice": "schedule",
      "confidence": 0.9,
      "probabilities": {
        "schedule": 0.94,
        "other": 0.06
      }
    },
    "mentions_date": {
      "type": "noul",
      "noul": 0.98
    }
  },
  "usage": {
    "input_tokens": 148,
    "output_tokens": 24
  }
}

Confidence and probability fields depend on question type and available evidence. Do not assume every answer has a separate confidence field.