Decisions API

Ask a decision model structured questions about a state.

The Decisions API sends a state and a set of questions to a model filling the decision role, and returns one structured answer per question.

POST /ai/v2/aiDecisions/decide
Authorization: Bearer <token>
Content-Type: application/json

{
  "state": { "shipment": "SHP-42", "delayHours": 30, "slaHours": 24 },
  "questions": {
    "escalate": { "type": "choice", "instructions": "Should this shipment be escalated? yes or no" }
  },
  "purpose": "shipment-triage"
}

Request

Field	Notes
`state`	Any JSON, up to 32,000 characters when serialised
`questions`	1 to 16 named questions, each with a `type` and `instructions`
`model`	Optional; defaults to the `decision` role
`purpose`	Optional label, up to 64 characters
`dataClassification`	Defaults to `internal`

Response

The response contains an id, the model that answered, an answers object keyed by question name, token usage and cost, and durationMs.

Errors

Status	Cause
413	The state is too large
422	A question is malformed
502	The decision provider failed

The audit log records who asked, which model answered and a hash of the state. The state itself is not logged.