Skip to main content
A decision model answers typed questions about a piece of content, the 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
A request costs a few hundredths of a cent, so you can put a decision model in front of or behind every agent call. New to decision models? Start with the Quickstart.

Endpoints

Authentication

Send your API key as x-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 a type, 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’s type, 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.
The headers and body from production:
The TypeSafe SDKs list models with 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-latest is an alias. The model field 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: