API reference · independent

How a decision API works

A decision API is a small contract. The caller sends a state and a map of typed questions; the service answers every question with a constrained value and a probability. There is no prompt to tune for format, no token budget for a reply, and no schema to repair.

This page describes the contract in general terms. For the hosted TypeSafe endpoint, keys, SDK names, and list pricing, see the Jev API reference; for gateway-specific model IDs and the Decisions route, see the OpenRouter page.

One state, several questions

The state is whatever the decision is about: a support message, a log excerpt, a tool call and its arguments, or a structured record. Questions are declared against that state. Because the answer space is fixed, asking several questions in one request costs one evaluation rather than a chain of chat calls.

request.json
{
  "state": "Invoice lists two seats, but only one user can sign in.",
  "questions": {
    "queue": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Charges, invoices, refunds, seats",
        "technical": "Bugs, outages, login problems",
        "other": "Anything else"
      }
    },
    "angry": { "type": "noul", "instructions": "Is the customer angry?" },
    "urgency": { "type": "score", "levels": [1, 5] }
  }
}

The three question types

TypeYou supplyYou get backTypical use
NoulA condition and its two outcomesA yes/no style value with a probabilityApproval gates, escalation flags, circuit breakers
ChoiceA closed set of option IDs with criteriaOne selected option plus per-option probabilitiesRouting, intent, tool selection, classification
ScoreAn ordered scale or numeric rangeA level on that scaleUrgency, relevance, quality, similarity

Field names differ between the TypeSafe request shape, OpenRouter Decisions, and Workers AI. Cloudflare documents 2–255 options for Choice and 2–10 levels for Score on Clef. Check the schema for the surface you are calling.

Thresholds instead of prompt instructions

The point of a returned probability is that the branching logic lives in code. "Auto-approve when the yes-probability is at least 0.8" is a line you can test, log, and change without touching a prompt. With generated text, the equivalent is usually a sentence asking the model to be confident, followed by a parser.

  • →Set the threshold from measured behaviour on your own data, not from a vendor example.
  • →Route low-confidence answers to a human, a slower model, or a safe default.
  • →Log the value and the threshold together — that is what makes the decision auditable.
  • →Re-baseline after a model version change; calibration claims are vendor-reported and not independently audited here.

Practical failure modes

  • →A closed answer space cannot express "none of the above" unless you add that option explicitly.
  • →Option IDs and their wording affect results; field tests report this on Workers AI.
  • →Long state can hit a request budget or be truncated near the limit — verify behaviour at the boundary.
  • →Confidence can be high on out-of-distribution input. A threshold is a policy, not a guarantee.

Frequently asked questions

Is a decision API the same as chat completions?

+

No. Chat completions generate a token stream; a decision endpoint takes state plus typed questions and returns constrained answers. On OpenRouter, Jev is served through the Decisions route and chat-completions SDKs do not work with it. Use the SDK or HTTP shape documented for the surface you chose.

Can I ask several questions in one call?

+

Yes — that is one of the main efficiencies. A single state can carry several Noul, Choice, and Score questions, and each returns its own typed answer. Cloudflare documents 1 to 64 questions per request on Workers AI.

What is a confidence threshold?

+

A numeric rule in your code: act on the returned value only when its probability clears a level you set, and escalate anything below it. It replaces a prompt instruction with a testable branch. Measure the right level on your own labels before you automate anything.

How is this different from JSON-schema structured output?

+

Structured output constrains the shape of generated text. A decision API constrains the answer space before inference: no generation, no output tokens to pay for, and no validation-and-retry path. What you give up is open-ended answers and explanations.

Where do I get an API key?

+

Keys for the hosted System One endpoint are issued by TypeSafe, not by this directory. A gateway such as OpenRouter is an alternative route with its own key and no separate TypeSafe account. This site does not issue or proxy keys.

Keep reading

Sources

Reviewed 2026-11-13. Vendor- and project-reported figures are labelled as such; none were independently reproduced by this site.

API reference · reviewed 2026-11-13 · first published 2026-11-13