Every automated system eventually arrives at the same fork in the road: maintain a pile of hand-written rules that nobody on the team fully understands anymore, or prompt a chat model to “reply in JSON” and spend the next quarter writing validation code around its inconsistencies. A decision API is the third option — a purpose-built endpoint that takes state and questions and hands back typed, calibrated answers your application can branch on immediately, without a parsing layer, a retry loop, or a prompt engineer on call.
What a Decision API Actually Returns
A decision API is not a text generator with a JSON mode bolted on. It is an interface built around a different contract: you send state and questions, and you receive answers already in the shape your code expects. With DecisionNode, that means one HTTPS endpoint — POST /v1/decide — that accepts text, JSON, or up to 16 images and video frames, along with questions defined in your code, and returns every answer in a single pass.
The output vocabulary is deliberately narrow, and that narrowness is the entire point. A choice returns one label from a set you define. A score returns a level on an ordered scale. A truth returns a calibrated probability between 0.00 and 1.00. A number returns a value on a grid. A point or box returns a location inside an image. None of these require a schema validator, a regex fallback, or a “sometimes it says ‘Priority: HIGH’ and sometimes it says ‘high priority'” cleanup function. A five-value label set is something a switch statement handles directly; an ordered score is something a ranking job sorts on.
The property that separates this from a typical chat completion is calibration. Every answer carries a confidence value, so the response tells you not just what the answer is but how sure the system is. That single number turns a model call into an actual decision primitive: code can act instantly above a threshold, and route to a review queue, a second narrower question, or a safe default below it. Building the same behavior out of general-purpose chat models is genuinely difficult, because their stated certainty does not reliably correlate with correctness — they are confidently wrong in ways that break threshold logic.
Determinism closes the loop. The same request, with the same inputs, returns the same answer. That makes decisions replayable: you can capture a production request, drop it into a unit test, and assert on the result. When you add a new label or shift a threshold, your test suite catches the regressions instead of your support queue. Teams replacing brittle hand-written rules usually discover that this testability, more than raw accuracy, is what they were actually missing.
Designing Decisions in Code, Not in Prompts
The workflow for a decision api inverts the prompt-engineering pattern. Instead of a long instruction string that drifts between environments, the questions live in your repository. You declare the label set for a routing decision — billing, shipping, technical, account, other — and the ordered scale for a risk score, and those declarations are versioned, code-reviewed, and deployed like any other interface. When the taxonomy changes, the change shows up as a diff in a pull request rather than a silent behavior shift in a production prompt.
That structure also makes the threshold pattern explicit. A typical ticket triage flow might look like this: send the ticket text and metadata to the endpoint, ask for a choice over your routing labels, and require a calibrated confidence of 0.92 or higher to auto-route. Above the threshold, the ticket is assigned and closed to human review. Below it, the system takes a second path — asking a narrower follow-up question, or queueing the ticket for a human with the model’s confidence and candidate label attached as context. The threshold is a constant in your configuration, not a vibe.
Because the answers are typed, the same pattern generalizes cleanly across domains. Promo-abuse checks ask for a truth value and compare against a tolerance; order and shipping decisions ask for a choice over fulfillment paths and a number for a quantity or delay estimate; moderation asks for a score and escalates only at the top of the scale. Nothing about the integration changes between these use cases — the endpoint, the request shape, and the response contract stay constant while the questions change.
Tooling is where this becomes practical rather than theoretical. SDKs for TypeScript, Python, Go, Ruby, and curl mean the first call is minutes away, while MCP tools, webhooks, and agent integrations let AI agents decide before they act — gating a tool invocation behind a typed decision with a confidence floor instead of letting a chat model improvise. For control loops above 10 decisions per second — drones, robots, simulators, machine monitoring — sessions over WebSocket keep the round trip predictable. And because output tokens are always free, there is no cost penalty for asking several questions in one request instead of spreading them across separate calls.
Operational Scenarios and the Latency Budget
The case for a decision API gets concrete when you put it inside a real operational budget. Two models cover the range: DecisionNode Flash at roughly 5 ms server-side and 19 ms end to end, priced at $0.035 per 1M input tokens, and DecisionNode MoE at roughly 9 ms, priced at $0.042 per 1M input tokens. Those numbers matter because they sit below the threshold where a network call stops feeling like a network call. A chat-style “reply in JSON” prompt that takes hundreds of milliseconds to several seconds is not viable inside a request handler, a scan loop, or a control path — 19 ms is.
That budget unlocks a set of workloads that were previously stuck between rule engines and nothing. Ticket routing and triage runs synchronously at intake. Fraud and promo-abuse checks run inline before an order is confirmed. Moderation, scoring, and gating attach to content pipelines and feature flags. On the physical side, quality control on production lines, warehouse monitoring, and traffic monitoring use image and frame inputs — up to 16 images per request — with point and box outputs locating defects or objects directly.
Boosters extend the base decision contract to specialized perception tasks without changing the integration: human age estimation, AI-generated image detection, face detection and recognition, OCR, and depth and segmentation. A warehouse system can combine an OCR read with a choice over damage categories in a single call, receive both with independent confidences, and apply a different threshold to each. Batch discounts make large backfills — re-scoring a historical ticket archive, for example — economically reasonable, and the free daily tier is enough to run a real evaluation before committing to an integration.
Operations teams tend to adopt the pattern for a quieter reason as well. When a decision is wrong, the debugging path is short: pull the stored request, replay it against the same endpoint, get the same answer, and inspect the confidence that was attached to it. That confidence value tells you whether the threshold was misconfigured, the label set was too coarse, or the input state was genuinely ambiguous — three very different fixes that are indistinguishable when all you have is a paragraph of model prose to read.
