Decisions API
One POST with the same key as chat: a state and questions in, probabilities out. Question types, the answer shape, examples in three languages and the billing rules are collected here.
The endpoint and authentication
A decision model writes no text: you pass a state and questions, it returns calibrated probabilities for each question. It uses the same key as chat.
| Method | Path | Purpose |
|---|---|---|
| POST | https://api.tokenator.top/v1/decisions | Answers to the questions about the given state. |
| GET | https://api.tokenator.top/v1/decisions/models | The decision models the key may use. |
The key goes in Authorization: Bearer sk-your-tokenator-key. For clients set up for OpenRouter, the same handler answers on /v1/alpha/decisions and /v1/api/alpha/decisions.
Your first request
curl https://api.tokenator.top/v1/decisions \ -H "Authorization: Bearer sk-your-tokenator-key" \ -H "Content-Type: application/json" \ -d '{ "model": "jev-latest", "state": "My checkout page shows a blank screen after I click Pay. I have tried two browsers.", "questions": { "is_bug": { "type": "noul", "instructions": "Is the customer reporting a software defect?", "criteria": { "true": "The customer describes broken or unexpected product behavior.", "false": "The customer is asking a question or requesting a feature." } }, "team": { "type": "choice", "instructions": "Which team should own this ticket?", "criteria": { "account": "Login, permissions, or profile issues.", "frontend": "Rendering, layout, or browser compatibility issues.", "payments": "Checkout, billing, or payment processing issues." } }, "urgency": { "type": "score", "instructions": "How urgent is this ticket?", "criteria": [ "Can wait for the next release", "Should be fixed this week", "Blocking revenue right now" ] } } }'
{
"id": "dec-6f1c9a2e4b7d0c3a5e8f91b2",
"model": "jev-latest",
"answers": {
"is_bug": { "type": "noul", "noul": 0.96 },
"team": {
"type": "choice",
"choice": "payments",
"confidence": 0.75,
"probabilities": { "account": 0, "frontend": 0.16, "payments": 0.84 }
},
"urgency": {
"type": "score",
"score": 1.99,
"confidence": 0.99,
"legend": {
"0": "Can wait for the next release",
"1": "Should be fixed this week",
"2": "Blocking revenue right now"
},
"probabilities": { "0": 0, "1": 0.01, "2": 0.99 }
}
},
"usage": { "input_tokens": 476, "output_tokens": 70 }
}The answer always has this shape: its own id, the Tokenator model name, answers keyed by your questions and usage. The provider's name, its request id and its cost never reach the client.
Three question types
| Type | What goes into criteria | What the answer carries |
|---|---|---|
noul | Yes or no: an object describing true and false, both required. | noul — the probability that true holds, from 0 to 1. |
choice | One option out of several: an object of option key → description, at least one option. | choice — the most likely option, confidence — how sure the model is, probabilities — the probability of every option. |
score | A level on an ordered scale: an array of levels from the lowest to the highest, with no empty level. | score — the expected level as a fractional index from 0, confidence, legend — index → level text, probabilities — the probability of every level. |
Which models answer questions
| Model | API ID | Context | Multiplier |
|---|---|---|---|
| Jev Latest | jev-latest | 32K tokens | 1.1× |
| Span-01 | span-01 | 32K tokens | 1× |
| Solar Decide | solar-decide | 524.3K tokens | 1.1× |
| D1 | d1 | 65.5K tokens | 1× |
| GPT-6 Luna Decisions | gpt-6-luna-decisions | 1.05M tokens | 1.1× |
Request parameters
| Field | Type | What it does |
|---|---|---|
model | string, required | The API ID of a model from the catalog. A model that is not marked as a decision one is refused with a 400 — the request never reaches the provider. |
state | string, object or array, required | What the questions are about: a ticket text, a database record, a conversation history. |
questions | object, required | The questions by key, from 1 to 256. Each has a type, instructions (the question itself) and criteria. The question key comes back as the answer key. |
provider, user, session_id, trace | optional | Accepted for compatibility with OpenRouter clients, but they go no further than Tokenator: Tokenator's routing picks the provider. |
From code
The OpenAI SDKs have no method for decisions, so this is a plain POST with JSON.
import requests result = requests.post( "https://api.tokenator.top/v1/decisions", headers={"Authorization": "Bearer sk-your-tokenator-key"}, json={ "model": "jev-latest", "state": "My checkout page shows a blank screen after I click Pay. I have tried two browsers.", "questions": { "is_bug": { "type": "noul", "instructions": "Is the customer reporting a software defect?", "criteria": {"true": "The customer describes broken or unexpected product behavior.", "false": "The customer is asking a question or requesting a feature."}, }, }, }, ).json() print(result["answers"]["is_bug"]["noul"])
const res = await fetch("https://api.tokenator.top/v1/decisions", { method: "POST", headers: { Authorization: "Bearer sk-your-tokenator-key", "Content-Type": "application/json", }, body: JSON.stringify({ model: "jev-latest", state: "My checkout page shows a blank screen after I click Pay. I have tried two browsers.", questions: { team: { type: "choice", instructions: "Which team should own this ticket?", criteria: { account: "Login, permissions, or profile issues.", frontend: "Rendering, layout, or browser compatibility issues.", payments: "Checkout, billing, or payment processing issues.", }, }, }, }), }) const { answers } = await res.json() console.log(answers.team.choice, answers.team.probabilities)
How decisions are billed
Only the input is paid for, as with the providers of these models themselves. The input_tokens figure from the provider's answer is multiplied by the model's multiplier and drawn from the key's limit. output_tokens shows in the answer but is not charged. When the provider sends no count, an estimate from the request size is charged.
The spending shows up in the key dashboard next to chat, and the remainder in /v1/tokens.
Error codes
| Code | When it comes | What to do |
|---|---|---|
400 model is required | The body carries no model field, or is not JSON. | Check Content-Type: application/json and a non-empty model. |
404 model_not_found | There is no model with that name in the catalog — most often a typo. | Check the ID against the table above or the /v1/decisions/models list. |
400 is not a decision model | The model is in the catalog, but it is not a decision one. | Use a model from the table above. Ordinary chat models work on /v1/chat/completions. |
400 needs instructions, has an unknown type | The request failed the check: no state or questions, a question without instructions or criteria, an unknown type. The message names the question key. | Fix the named question. Such a request never reaches the provider and costs nothing. |
401 | The key is missing, expired or revoked. | Check the Authorization: Bearer header and the key's expiry in your account. |
502 Request error | An error on the provider side. Its text is not passed through. | Retry — Tokenator fails over to the next provider on its own. If it persists, contact support. |
503 Model temporarily unavailable | No provider of the model answered. | Retry later or pick another model from the table. |
FAQ
How does a decision model differ from a chat one?
It writes no text, it judges: a state and questions go in, a probability for each comes out. The answer always has one shape, so nothing has to be parsed out of text, and it is noticeably cheaper than asking a chat model for JSON: only the input is paid for.
Why does a model answer 400 on /v1/decisions?
The endpoint serves only models marked as decision ones. The list is in the table above and in the catalog under the Decisions filter. A request with an ordinary chat model is refused before the provider is contacted, so such an error costs nothing.
Can I reach a decision model from chat?
No. On /v1/chat/completions, /v1/responses and /v1/messages such a model answers 400 naming the right path. It is not in the general /v1/models list either, as on OpenRouter: it shows under /v1/models?output_modalities=decisions and /v1/decisions/models.
How many questions can I ask at once?
Up to 256 in one request. Together with the state they have to fit into the model's context — it is in the table above and on the model page.
Does Tokenator store what I send?
The request body goes into the key's technical log, as with every other endpoint. What exactly is kept and for how long is described in the security section.