Deciders
Versioned question sets answered against an input, producing append-only decisions confined to each question's answer space.
Overview
A decider is a named set of questions. Asked about an input — a ticket, a message, a record — it produces a decision: one answer per question. The questions, the input and the answers are the shapes of OpenAI's Decisions API, and every decision names the question-set version it was answered under.
A decider is answered by exactly one backend: a tool-less
agent, which is shown the questions and the input and answers
within a schema compiled from them, or an http or pipeline
tool of yours, which receives { input, questions } and answers
in the contract below. A tool that forwards to OpenAI's /v1/decisions, with
model as a preset, answers a decider as it is.
This module is a verbatim mirror of the runtime: every field, method, status
code and error shape is the runtime's own, re-rooted under the project in the
path. It serves two collections — /deciders and /decisions — under that
project prefix.
Deciders are not gated by plan. A decision is a run: it counts against the plan's monthly runs, and one answered by an agent on a managed provider spends the balance like any other generation.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Deciders.
Data Model
Decider
| Field | Type | Description |
|---|---|---|
policy_ids | string[] | The policies every decision's backend acts under. Empty for one written without any, which does not run until a write gives it one. |
id | string | |
project_id | string | |
name | string | |
description | string, nullable | |
agent_id | string, nullable | The tool-less agent that answers; null when a tool does |
tool_id | string, nullable | The tool that answers, run with no action; null when an agent does |
version | integer | The question set's version. Bumped only by a write that changes questions. |
questions | object[] | The questions, in the order the model is shown them. |
created_at | string (date-time) | |
updated_at | string (date-time) |
name is unique within the project. tool_id names an http or pipeline
tool. A decider holds 1 to 20 questions.
Decision
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
decider_id | string, nullable | The decider asked; kept after the decider is deleted. Null for a decision sent with its own questions. |
decider_version | integer, nullable | The question-set version the decision was answered under |
questions | object[], nullable | The questions a decision sent with its own was answered under. Null for a decider's decision, whose questions are its decider_version. |
status | queued | running | completed | failed | |
answers | object[], nullable | One answer per question, in question order. Null until the decision completes, then never rewritten. |
answers_by_name | object, nullable | The same answers keyed by question name, so a JSON Logic path reads one by name (answers_by_name.department.choice) rather than by position. |
error | object, nullable | Why a failed decision failed. |
generation_id | string, nullable | The generation that answered, once one has; null for a tool backend. Its receipt carries what the decision cost. |
metadata | object | Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase. No key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag. |
created_at | string (date-time) | |
updated_at | string (date-time) |
id is the polling handle. metadata holds your own identifiers, written once
with the decision.
The evaluated input is not stored. Put the id of what was judged in metadata
to find the decision again.
Key Concepts
Questions and answers
Every question has a type, a name (unique, letters, digits and
underscores) and instructions.
type | Declares | Answer |
|---|---|---|
predicate | nothing more | { "type": "predicate", "name", "probability" } |
choice | choices: 2 to 20 { value, description } | { "type": "choice", "name", "choice", "probabilities"?, "confidence"? } |
score | levels: 2 to 20 ordered { label, description } | { "type": "score", "name", "score", "probabilities"?, "confidence"? } |
An agent answers a predicate with probability 1 or 0 and a score with the
level index. probabilities ([{ value, probability }], plus label on a
score) and confidence come only from a tool, carried as it supplied them; a
tool may answer a score between two levels.
Input
input is a string; a list of user messages whose content is a string or
input_text and base64 input_image parts; or any other JSON value, which an
agent is shown as indented JSON.
Versions
Changing questions archives the previous set and moves version; a rename, a
new description or a new backend does not. Read the questions a decision was
answered under with
GET /v1/projects/{project_id}/deciders/{decider_id}/versions/{version},
and pass expected_version on
PATCH /v1/projects/{project_id}/deciders/{decider_id}
to refuse a stale write with 409.
A tool backend
The tool is called with { "input": …, "questions": [ … ] } and answers
{ "answers": [ { "name": …, "probability" | "choice" | "score": …, … } ] },
one entry per question in any order. Any other answer field, a repeated or
unknown name, or a value outside the answer space fails the decision with
DECISION_ANSWER_INVALID. An engine that speaks a close dialect is bridged
with a pipeline tool: a step's input maps the request, the pipeline's
output maps the answer.
A client, mcp tool, or a tool whose preset_parameters set input or
questions, cannot answer a decision: 400 DECIDER_TOOL_NOT_CALLABLE. A tool a
decider names cannot be deleted (409 TOOL_HAS_DEPENDENTS), nor can its agent.
Decision authority
A decision's backend runs under the decider's policy_ids, capped by the
caller who requests it. A backend that grant may not start
(agents:CreateAgentGeneration or tools:CallTool) is refused
403 ACTION_NOT_HELD before the decision is recorded, even when the caller may
start it. Changing policy_ids leaves version alone. A decider with empty
policy_ids is allowed nothing; an inline decision runs as its caller.
policy_ids is required on create (400 VALIDATION_FAILED), and every write
needs the backend's start action. The writer must hold every grant the
policies carry (403 POLICY_GRANT_NOT_HELD); a policy a
decider names cannot be deleted (409 POLICY_HAS_DEPENDENTS).
Requesting a decision
POST /v1/projects/{project_id}/deciders/{decider_id}/decisions
takes input, optional metadata and wait.
POST /v1/projects/{project_id}/decisions
takes the questions with the request, as OpenAI's endpoint does, and names
agent_id or tool_id in place of model. With wait omitted the answer is
201 with the decision queued; poll
GET /v1/projects/{project_id}/decisions/{decision_id}
or subscribe to decisions.completed and decisions.failed on a
webhook. With wait: true it is 201 with the decision
settled. A failed decision is terminal: request a new one. Its error follows
the generation's rule for the provider's own
answer.
Before anything reaches the runtime, a decision clears the same gates a
generation does. Its backend is read off the decider, or off the body of an
inline one: a decision an agent on a managed provider answers is refused
while the balance is negative (402 INSUFFICIENT_CREDIT), and its model must
carry a price (409 MODEL_NOT_PRICED);
one a tool answers is a run that spends no credit.
Either is refused when a Free account is out of runs (403 PLAN_LIMIT_REACHED).
This holds however the decision arrives: a call to this API or an agent's tool
call.
Examples
Create a decider over an agent
pol_V1StGXR8Z5jdHi6B allows agents:CreateAgentGeneration on the agent
(Decision authority).
- CLI
- SDK
- curl
naturali create-decider \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-triage \
--policy-ids pol_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--questions '[
{
"type": "choice",
"name": "route",
"instructions": "Which team should own this ticket?",
"choices": [
{ "value": "billing", "description": "Charges, refunds, invoices" },
{ "value": "technical", "description": "Errors, outages" }
]
},
{
"type": "predicate",
"name": "needs_human",
"instructions": "Must a person read this before any automated reply?"
}
]'
const { data: decider } = await naturali.deciders.createDecider({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'support-triage',
policy_ids: ['pol_V1StGXR8Z5jdHi6B'],
agent_id: 'agent_V1StGXR8Z5jdHi6B',
questions: [
{
type: 'choice',
name: 'route',
instructions: 'Which team should own this ticket?',
choices: [
{ value: 'billing', description: 'Charges, refunds, invoices' },
{ value: 'technical', description: 'Errors, outages' },
],
},
{
type: 'predicate',
name: 'needs_human',
instructions: 'Must a person read this before any automated reply?',
},
],
},
});
console.log(decider?.id, decider?.version);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/deciders \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "support-triage",
"policy_ids": ["pol_V1StGXR8Z5jdHi6B"],
"agent_id": "agent_V1StGXR8Z5jdHi6B",
"questions": [
{
"type": "choice",
"name": "route",
"instructions": "Which team should own this ticket?",
"choices": [
{ "value": "billing", "description": "Charges, refunds, invoices" },
{ "value": "technical", "description": "Errors, outages" }
]
},
{
"type": "predicate",
"name": "needs_human",
"instructions": "Must a person read this before any automated reply?"
}
]
}'
Request a decision and wait for it
- CLI
- SDK
- curl
naturali create-decision \
--project-id proj_V1StGXR8Z5jdHi6B \
--decider-id dcd_V1StGXR8Z5jdHi6B \
--input 'I was charged twice for the same order.' \
--metadata '{ "ticket_id": "ZD-48213" }' \
--wait true
const { data: decision } = await naturali.deciders.createDecision({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B', decider_id: 'dcd_V1StGXR8Z5jdHi6B' },
body: {
input: 'I was charged twice for the same order.',
metadata: { ticket_id: 'ZD-48213' },
wait: true,
},
});
console.log(decision?.status, decision?.answers);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/deciders/dcd_V1StGXR8Z5jdHi6B/decisions \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"input": "I was charged twice for the same order.",
"metadata": { "ticket_id": "ZD-48213" },
"wait": true
}'
Ask questions inline
- CLI
- SDK
- curl
naturali create-inline-decision \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--questions '[{ "type": "predicate", "name": "refund", "instructions": "Is the customer asking for money back?" }]' \
--input 'I was charged twice for the same order.' \
--wait true
const { data: decision } = await naturali.deciders.createInlineDecision({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
agent_id: 'agent_V1StGXR8Z5jdHi6B',
questions: [
{
type: 'predicate',
name: 'refund',
instructions: 'Is the customer asking for money back?',
},
],
input: 'I was charged twice for the same order.',
wait: true,
},
});
console.log(decision?.answers);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/decisions \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_V1StGXR8Z5jdHi6B",
"questions": [{ "type": "predicate", "name": "refund", "instructions": "Is the customer asking for money back?" }],
"input": "I was charged twice for the same order.",
"wait": true
}'