Every nontrivial system eventually hits the same wall: something arrives as messy, real-world signal — a support ticket, a product photo, a sensor frame, a checkout attempt — and your code needs a discrete decision about it. Historically you had two bad options. You wrote hand-tuned rules that grew into an unmaintainable forest of if/else branches, or you called a chat model, asked it to “reply in JSON,” and spent the next quarter writing parsers, retries, and validation layers for output that changed shape every Tuesday. A decision API is the third option: an endpoint that takes state plus questions you define in code and returns typed, calibrated answers in a single pass. This article looks at how that primitive works, how to design against it, and where it pays off.
What a Decision API Is — and Why Typed Output Beats Generated Text
The core idea is deceptively simple. You POST a payload to a single HTTPS endpoint. The payload contains state — text, JSON, or up to 16 images and video frames — and a set of questions expressed as a schema rather than a prose prompt. The response is not a paragraph. It is a structured object whose every field conforms to one of a small set of answer types, each with a defined semantics your compiler or validator can check.
Those answer types are worth memorizing, because they cover most operational decisions:
choice returns exactly one of the labels you supplied — a department, a category, an action. score returns a level on an ordered scale you define, such as low/medium/high or a 1–5 severity ladder. truth returns a calibrated probability between 0.00 and 1.00, which is the primitive you want for anything resembling a fraud flag or an abuse signal. number returns a value snapped to a grid you specify. point and box return coordinates inside an image, so visual questions land in the same response as textual ones.
The differentiator is calibration. A probability of 0.82 is not a vibe — it is a statement you can act on programmatically. That single property lets you write threshold logic that behaves predictably in production: act instantly above the threshold, re-check, queue for review, or take the safe path below it. You are no longer guessing whether the model “sounded confident.”
Equally important is determinism. The same request produces the same answer, which means decision logic becomes replayable and testable. You can snapshot a payload, assert against the response in CI, and diff behavior across model versions the way you would diff any other code. Sampling-based text generation cannot offer that, and it is the main reason “ask the chatbot for JSON” pipelines remain fragile in regulated or high-volume environments.
Latency and cost profiles are likewise shaped by the absence of generation. DecisionNode, for example, runs its Flash model at roughly 5 ms server-side and about 19 ms end to end, priced at $0.035 per 1M input tokens, with a heavier MoE model at roughly 9 ms and $0.042 per 1M input tokens. Output tokens are free, because there are none in the generative sense — the answer is a decision, not a composition. That is what makes the pattern viable inside a request handler rather than as a background job.
Designing Decision Contracts in Code
The practical shift when adopting a decision API is that prompt engineering becomes schema engineering. Instead of coaxing a model toward a format, you declare the questions your service needs and let the platform guarantee the shape of the answer. A routing service might declare a choice over its queue labels, a truth over whether the message contains a billing dispute, and a score for urgency. A fulfillment service might declare a choice over carrier selection and a truth over whether an address looks deliverable. Those declarations live next to the code that consumes them, versioned in the same repository, reviewed in the same pull requests.
This changes how you handle failure. With untyped output, failure means a parse error at runtime and a 500 in the logs. With a typed contract, a malformed answer is impossible by construction, so your engineering effort moves to the genuinely interesting part: what to do at each confidence band. A common pattern is a three-tier policy — auto-approve above 0.9, route to a lightweight secondary check between 0.7 and 0.9, and hand to a human or a conservative default below that. Because the confidence is calibrated, the bands mean roughly what they say across traffic mixes, and you can tune them against real outcomes instead of intuition.
Throughput matters too once decisions move inside hot loops. Request/response works well for typical API traffic, but sustained loops above roughly ten decisions per second are better served by persistent sessions over WebSocket — the pattern used for drones, robots, simulators, and continuous machine monitoring, where a device needs a fresh judgment on every frame or tick rather than on every user action.
It also helps to lean on pre-built perception rather than reinventing it. Platforms such as decisionnode.com ship boosters for human age estimation, AI-generated image detection, face detection and recognition, OCR, depth, and segmentation, which means a single request can carry both raw pixels and a typed question about them. Combined with SDKs for TypeScript, Python, Go, Ruby, and curl, plus MCP tools and webhooks for agent workflows, the integration surface stays small: build the payload, call the endpoint, branch on the answer. The same request shape works whether the caller is a backend service, a cron job, or an autonomous agent deciding before it acts.
Where Decision APIs Earn Their Keep
The pattern is easiest to justify wherever a decision has a small, enumerable answer space and a real cost of being wrong. Ticket routing and triage is the canonical case: a choice over queue labels plus a score for urgency, dispatched in the time it takes to open a database connection, with low-confidence tickets held for human review instead of being silently misrouted. Fraud and promo-abuse checks map naturally to the truth type — a calibrated probability that a redemption or signup is abusive, evaluated against a threshold policy that trades false positives against losses explicitly rather than implicitly.
Order and shipping decisions benefit from typed answers combined with multimodal input: a warehouse photo, a declared address, and a carrier rule set can all resolve into a choice plus a confidence, and below-threshold cases route to an operator. Moderation pipelines use the same shape to separate clear violations from ambiguous ones, which keeps human reviewers focused on the genuinely uncertain slice of the queue rather than the whole of it.
Physical operations are where latency stops being abstract. Quality control on production lines needs a per-unit verdict in milliseconds, with a box locating the defect in the frame so downstream machinery can act on it. Warehouse and traffic monitoring run continuous loops where a WebSocket session delivering point and box answers at frame rate replaces a fragile stack of thresholding scripts and separate CV microservices.
Finally, there is the agent case. AI agents are increasingly the components that take actions rather than the components that write prose, and an agent that can call a decision API before acting gains a typed guardrail: a calibrated probability that the next step is safe, checkable in code, deterministic under replay, and cheap enough to invoke on every turn. That is the difference between an agent that reasons eloquently and one that behaves consistently when the stakes are real.
Born in Dresden and now coding in Kigali’s tech hubs, Sabine swapped aerospace avionics for storytelling. She breaks down satellite-imagery ethics, Rwandan specialty coffee, and DIY audio synthesizers with the same engineer’s precision. Weekends see her paragliding over volcanoes and sketching circuitry in travel journals.