Decisions
POST /v1/decisions, with /v1/systemone as an alias, answers typed questions about a shared
state with calibrated probabilities instead of text. The request uses the System One shape that
decision models accept. The TypeSafe SDK works with Keln once you change its base URL, and clients
built for other gateways' decision endpoints send the same body. It uses the same API key and the
same billing as chat completions. The Decisions capability page
covers what decisions are good for. This page lists the request, the response and the errors.
curl https://api.keln.ai/v1/decisions \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cloudflare/clef",
"state": "I was charged twice for my subscription this month and I want the extra charge refunded.",
"questions": {
"refund": { "type": "noul", "instructions": "Is the customer asking for money back?" },
"department": { "type": "choice", "instructions": "Which team should handle this?",
"criteria": { "billing": "Charges and refunds", "technical": "Bugs and outages" } },
"urgency": { "type": "score", "instructions": "How urgent is this?",
"criteria": ["Can wait", "This week", "Blocking revenue now"] }
}
}'
{
"model": "cloudflare/clef",
"answers": {
"refund": { "type": "noul", "noul": 0.98 },
"department": { "type": "choice", "choice": "billing", "confidence": 0.98,
"probabilities": { "billing": 0.99, "technical": 0.01 } },
"urgency": { "type": "score", "score": 1.0, "confidence": 0.47,
"legend": { "0": "Can wait", "1": "This week", "2": "Blocking revenue now" },
"probabilities": { "0": 0.11, "1": 0.79, "2": 0.10 } }
},
"usage": { "input_tokens": 322, "output_tokens": 0, "cost": 0.0000773 }
}
To use the TypeSafe SDK, set its base URL to Keln:
from typesafe_sdk import TypeSafeClient
client = TypeSafeClient(api_key=KELN_API_KEY, base_url="https://api.keln.ai")
result = client.system_one(state, questions, model="cloudflare/clef")
print(result.answers["refund"].noul)
Or set TYPESAFE_BASE_URL=https://api.keln.ai and TYPESAFE_API_KEY, and create the client without arguments.
The SDK's default model alias (jev-latest) resolves to the pinned id that GET /v1/models lists
under aliases. Keln accepts images attached through the SDK
(Image.from_base64, assets=) and its zstd-compressed bodies as the SDK sends them. client.models.list()
expects TypeSafe's own list format and can't read Keln's catalog. Call GET /v1/models instead.
Request
| Field | Contract |
|---|---|
model |
a decision model id from GET /v1/models: the rows whose output_modalities is ["decisions"]. Each row also lists the aliases it answers to; send any of them and the answer names the pinned id. Keln returns 400 wrong_endpoint for a chat model on this endpoint, and for a decision model on chat completions. |
state |
what every question is about: a string, a JSON object, or an array of parts. Parts are {"type": "text", "text": …} and {"type": "image_url", "image_url": {"url": "data:image/png;base64,…"}} (PNG or JPEG as a data URL. Keln does not fetch remote URLs.). Images go to models whose catalog row lists image under input_modalities; each model has its own size and count limits, and a request no model accepts gets a 400 image_not_supported naming the limit. |
questions |
an object keyed by names you choose. Each question has a type and instructions; the answer comes back under the same name. |
type: "noul" |
a yes/no proposition. Optional criteria with true and false descriptions. Answer: noul, the probability of yes. |
type: "choice" |
pick one option. criteria maps each option to a description (or null), 2 to 255 options. Answer: choice, probabilities per option, confidence. |
type: "score" |
a position on an ordered scale. criteria is an array of level descriptions, lowest first, 2 to 10 levels. Answer: score (the probability-weighted level index, so it can fall between levels), legend, probabilities per level, confidence. |
| anything else | Keln does not forward other fields. It removes user and safety_identifier (privacy) and ignores unknown keys. |
Every question is answered independently against the same state, in one call. A request can carry up to 400
questions. Keln skips models with a lower limit. If no model can take the request, Keln returns a
400 that names the reason.
What you get
model is the Keln id you asked for, answers is keyed by your question names, and usage carries
input_tokens, output_tokens and cost. confidence appears when the answering model returns
it. Keln returns the model's probabilities unchanged.
Billing
Decision models bill input tokens only. Keln reports output_tokens as the model counted them,
and they're free. usage.cost is the exact charge, from the per-model price on
GET /v1/models.
Errors
| Code | Meaning |
|---|---|
format_not_supported |
the body is in OpenAI's Decisions format (input + a questions array). Send the System One shape above. |
stream_not_supported |
decisions are not streamed; send the request without stream. |
question_type_not_supported |
a type other than noul, choice, score (or box on a model that does not answer it). |
question_shape_not_supported |
a choice with one option or a score with one level, or a shape no serving model accepts. |
image_not_supported |
a remote image URL, an unsupported format, or an image count or size no serving model accepts. |
wrong_endpoint |
a chat model on this endpoint, or a decision model on chat completions. |
model_not_found, modality_not_supported, rate and balance errors |
as on every Keln endpoint (errors & limits). |
Rate limits, keys, budgets and zero data retention work the same as on chat completions.