state, and returns calibrated probabilities instead of generated text. One request can ask several questions, and each answer comes back as a number or a pick you can branch on directly, with no parsing and no prompt to coax a format out of an LLM.
Use a decision model instead of an LLM agent when the output is a decision, not prose:
- Classifying: which category, team or intent a message belongs to
- Routing: which agent, swarm type or model should handle a task
- Gating: whether a task needs an expensive agent call at all
- Grading: how good an answer is before it ships
Endpoints
Authentication
Send your API key asx-api-key: <key> or Authorization: Bearer <key>. A missing, unknown, revoked or malformed key returns 401. Get a key at swarms.world/platform/api-keys.
Request
POST /v1/decision/completions takes:
Several questions go in one request and the state’s tokens are billed once, so asking three questions about a ticket costs about the same as asking one.
Question Types
Every question has atype, optional instructions saying what to decide, and criteria. instructions and the descriptions inside criteria can be a string, an object or a list.
Answers
Every answer includes its question’stype, plus:
Response
POST /v1/decision/completions returns:
A live response from production:
usage.total_cost is the amount charged for the request.
Response Headers
Both completion endpoints set:SystemOne (TypeSafe API Format)
POST /v1/systemone takes and returns exactly what the TypeSafe API’s POST /v1/systemone does, so code and SDKs written for TypeSafe work with the base URL set to https://api.swarms.world and a Swarms API key. It runs the same models at the same prices as /v1/decision/completions.
GET /v1/models and send an X-TypeSafe-SDK header. With that header, /v1/models returns the decision model list in the same shape as GET /v1/decision/models instead of the OpenAI-style model list. See SystemOne: Use the TypeSafe Format for a worked example.
Models and Pricing
GET /v1/decision/models returns every model this API can run:
On 2026-11-03 the TypeSafe models were
jev-latest, jev-preview and the pinned jev-1.13.0, each at $0.0483 per 1M input tokens with output tokens free. Read prices from the endpoint rather than copying them into code, because the list changes as versions ship.
jev-latestis an alias. Themodelfield of every response shows the version that answered, which can be newer than the pinned versions in the list. Pin a listed version when answers must stay comparable over time.- A name that isn’t in the list returns
400(Unknown model).
Billing
- A request costs
input_tokens × input_cost_per_1m / 1,000,000, plus the same for output tokens. No night-time or other discount applies. - You’re charged only after the model answers. A request that fails, including an unknown model or a provider error, is not charged.
- Your purchased credit balance must be above the $1.00 minimum, as on the other completion endpoints.
- Decision completions count toward your rate limits like other completions.
Errors
A
422 for an unknown question type, from production:
Related
- Decision Models Quickstart: your first request in five minutes
- API reference: Execute Decision Model Completion, Execute Decision Model Completion (TypeSafe API), Get Decision Models and Prices
- Examples:
- Decision Model Completion: one request with a
noul, achoiceand ascorequestion - List Decision Models and Estimate Costs: prices, pinned versions and cost math
- SystemOne: Use the TypeSafe Format: Bearer auth, headers and the TypeSafe model list
- Gate and Judge an Agent: decide whether to run an agent, then grade its answer
- Pick a Swarm and the Best Draft: choose the swarm type, then the best output
- Decision Model Completion: one request with a