Most teams that try to make software “smart” end up in the same place: a prompt that asks a chat model to reply in JSON, a parser that fails one time in fifty, a retry loop, and a validation layer bolted on afterwards. The reasoning might be fine, but the interface is wrong. A chat model produces text; production code needs a value — one of your labels, a number on your scale, a coordinate inside your image, a probability you can compare against a threshold. That mismatch is exactly the problem a decision api is built to eliminate. Instead of generating prose and hoping it parses, a decision API accepts state plus questions defined in code and returns schema-valid, typed answers in a single pass. This article looks at how that contract works, why calibrated confidence matters more than raw accuracy, and how teams are wiring these endpoints into latency-sensitive systems.
What a Decision API Actually Is — and Why It Is Not a Chat Model Wrapper
A decision API is an HTTP service with a narrow, predictable contract. You send two things: state (the evidence — text, structured JSON, or up to 16 images or video frames) and a question set defined in code (the labels you allow, the ordered scale you care about, the region of the image to inspect). You get back an answer object whose fields are already the types your application uses. On DecisionNode, that is a single endpoint — POST /v1/decide — and the response types are fixed: choice (one label from your list), score (a level on an ordered scale), truth (a calibrated probability from 0.00 to 1.00), number (a value on a grid), point and box (locations in an image).
The distinction from a general-purpose language model is architectural, not cosmetic. When you ask a chat model for JSON, the model is still generating tokens in an open-ended space, then a schema validator rejects the output when it drifts. A decision model is trained to return a member of a closed set. The label space is part of the request, so there is no such thing as a syntactically invalid answer — the worst case is a low-confidence answer, which is a business problem you can handle, not a parsing exception that pages someone at 3 a.m.
That closed-set design changes how you write the calling code. Instead of a defensive block that strips code fences, retries with a stricter prompt, and logs malformed payloads, you write a type switch. In TypeScript or Go, the response maps directly onto a union type or a struct; in Python, onto a dataclass. SDKs for TypeScript, Python, Go, Ruby and curl make that mapping explicit, and the same endpoint is reachable from MCP tools, webhooks and AI agents that need to decide before they act rather than after.
It also changes testing. DecisionNode is deterministic: the same request returns the same answer. That means you can record real traffic, replay it in CI, and assert on exact outputs — something that is effectively impossible with sampling-based text generation. For teams replacing brittle hand-written rule engines, the appeal is obvious: rules are deterministic but rigid, chat models are flexible but non-deterministic, and a decision API is meant to be both flexible and replayable. The question stops being “did the model behave?” and becomes “is the threshold set correctly for this route?” — a question a product owner can actually answer.
Typed Answers and Calibrated Confidence: Designing Around the Decision Contract
The most underrated output type is truth — a probability between 0.00 and 1.00. Raw classifiers usually hand you a score whose numeric meaning is opaque; a softmax value of 0.87 does not tell you that 87 out of 100 such cases are positive. Calibration is the property that makes that number usable: every answer carries a calibrated confidence, so a 0.90 really should be right about nine times in ten across the population of requests that receive it. When that holds, you can set thresholds with intent instead of guessing.
In practice, this produces a three-band pattern that shows up in almost every deployment. Above a high threshold, code acts immediately with no human in the loop. Below a low threshold, it takes the safe path — escalate to a queue, request more evidence, block by default, or ask a second question. In between, it routes to a slower, more expensive check. The value is that the threshold is a configuration decision, not a model retrain. A fraud team tightening precision during a promo campaign, or a support org deciding how many tickets it can afford to auto-route, can shift a cutoff without touching inference code at all.
Compare that to the chat-model pattern. There, confidence is often whatever the model says about itself in a sentence — a self-report that is neither calibrated nor guaranteed to appear. You end up sampling multiple completions to estimate agreement, which multiplies latency and cost while still leaving you with a heuristic. Calibrated confidence is cheaper and more honest: one call, one number, one comparison.
Schema design matters here too. Resist the urge to ask one giant question. Decompose into the smallest set of typed questions that your downstream logic actually branches on: an intent as a choice, an urgency as a score, a contains-PII flag as a truth, and a damage region as a box. Each answer arrives with its own confidence, so a routing service can auto-assign on a high-confidence intent while still sending the image region to a reviewer. Because requests can carry text, JSON and up to 16 images or frames in one call, a single decision round-trip can cover a multimodal ticket — the customer’s message, the order record, and the photo of the damaged item — without orchestrating three separate model calls and stitching the results.
Latency, Determinism, and the Hot Path: Where Decision APIs Earn Their Place
The reason teams move decision logic out of prompts and into an API is usually a latency budget that a chat model cannot meet. DecisionNode publishes two models: Flash, at roughly 5 ms server-side and 19 ms end to end, and MoE, at roughly 9 ms, at $0.035 and $0.042 per 1M input tokens respectively, with output tokens always free. Those numbers matter because they sit inside the range where a decision can be made inline — during a checkout request, a sorting-belt scan, or an agent’s tool loop — rather than as an asynchronous enrichment step that arrives too late to change the outcome.
For throughput beyond roughly 10 decisions per second per process, sessions over WebSocket replace request/response chatter and keep the loop tight. That is the pattern behind drones, robots, simulators and continuous machine monitoring, where the decision cadence is tens or hundreds per second and a per-call handshake is pure overhead. At the other end of the spectrum, batch discounts and a free daily tier make it practical to backfill historical records — scoring a year of past orders to see what a new threshold policy would have done before you ship it.
Concrete deployment patterns cluster into a few recognizable shapes. Ticket routing and triage: a choice over queue labels plus a score for urgency, with low-confidence tickets held for a human. Fraud and promo abuse: a truth output per rule, combined into a single gate, with the safe path being manual review. Order and shipping decisions: choice over fulfilment options constrained by a number output for delivery estimate. Moderation and gating: high-precision auto-blocks with an appeals lane for the middle band. On the operational side, quality control on production lines, warehouse monitoring and traffic monitoring lean on the vision types — a box for a defect, a point for a vehicle — often with boosters such as OCR, segmentation, depth, face detection, AI-generated image detection or human age estimation layered in when the raw question needs a specialised prior.
The integration details are unglamorous but decisive. Idempotent request IDs let you retry safely; deterministic responses let you cache and diff; typed outputs let you log a decision as structured data rather than a blob of text, which makes audit trails and post-hoc analysis tractable. AI agents benefit most directly — an agent that calls a decision API before acting gets a label and a confidence it can branch on, instead of a paragraph it must interpret. For engineers tired of building parsers around probabilistic text, that is the whole pitch: ask a question in code, get an answer you can compile against.
A Parisian data-journalist who moonlights as a street-magician. Quentin deciphers spreadsheets on global trade one day and teaches card tricks on TikTok the next. He believes storytelling is a sleight-of-hand craft: misdirect clichés, reveal insights.