Decision API: Typed, Calibrated Answers Instead of Another Chat Completion

Most teams that bolt a large language model onto a product eventually hit the same wall. The model returns prose, the prose has to be parsed, the parser breaks on edge cases, and a feature that took a weekend to prototype takes a quarter to make reliable. The problem is rarely the model’s intelligence. It is the output contract. Generated text is a flexible medium for humans and a hostile one for code.

A decision API inverts that arrangement. Rather than asking a model to write something and hoping it can be parsed, the caller declares the questions in code, sends state, and receives a typed answer that already conforms to a schema. For developers, product teams, and ops engineers, that shift changes the entire shape of the integration: no prompt-fragile parsing layer, no retry storms against malformed JSON, and no ambiguity about what a returned value means or how much to trust it.

What a Decision API Returns: Choice, Score, Truth, Number, Point, Box

The contract is deliberately small. A single HTTPS request carries state — free text, structured JSON, or up to sixteen images and video frames — alongside the questions that matter at that step in the workflow. The response contains typed answers rather than narration: choice (one of the labels supplied in code), score (a level on an ordered scale), truth (a calibrated probability between 0.00 and 1.00), number (a value on a grid), and point or box (a location inside an image). Everything is produced in a single pass, so a ticket triage call can return a category, an urgency score, and a probability that the customer is about to churn without three round trips.

Each answer carries calibrated confidence, and that is the part most teams underestimate. A raw model score of 0.8 is meaningless unless 0.8 genuinely corresponds to roughly an 80 percent hit rate on comparable inputs. Calibration makes confidence actionable. A routing service can auto-assign a ticket above 0.95, push it to a human queue between 0.70 and 0.95, and fall back to a default owner below that. That logic is ordinary branching code — no second model call to “check” the first one, no prompt tweaking to coax a different answer.

Because the questions live in code rather than in an improvised prompt, the schema is versionable. Change a label set, add a score band, introduce a new truth question, and the diff shows up in review like any other contract change. Typed answers also mean typed tests: fixtures of known inputs with expected choices and acceptable confidence bands, executed in CI exactly like any other unit test. Determinism closes the loop. The same request returns the same answer, which removes an entire class of flaky integration tests and makes incident review tractable — when a decision looks wrong in production, the state can be replayed exactly as it was.

This is also where a decision API differs most sharply from a booster or a classifier library. The output is not a label with an opaque score attached; it is a decision with an explicit confidence attached, ready to be consumed by the rest of the system without translation. Schema-validity is a property of the endpoint rather than something enforced by a downstream validator that silently drops records when it fails.

Latency, Cost, and the Shape of a Decide Call

Decision endpoints are usually evaluated on three numbers: how fast, how much, and how predictable. All three matter more than raw benchmark scores for most production workflows, because a decision that arrives after the user has moved on is worth nothing regardless of its accuracy.

DecisionNode operates two model tiers for this reason. DecisionNode Flash answers in roughly 5 ms server-side and about 19 ms end to end at $0.035 per 1M input tokens, which puts a decision inside the budget of a synchronous API request or an interactive UI action. DecisionNode MoE runs at roughly 9 ms for $0.042 per 1M input tokens when a request benefits from a larger mixture-of-experts model. Output tokens are always free, batch discounts are available, and a free daily tier exists for development and low-volume testing. Compare that to the common pattern of prompting a chat model to “reply in JSON”: hundreds of milliseconds to multiple seconds, billed output tokens for the JSON scaffolding, and variance that spikes exactly when traffic does.

Throughput is the other axis. A request-per-decision model stops making sense once a loop exceeds about ten decisions per second. Sessions over WebSocket handle that regime, which is what makes the same primitive usable for drones, robots, simulators, and machine monitoring — systems where a decision has to land inside a control cycle rather than inside a page load.

Image-heavy work is handled without bolting on extra services. Boosters for human age estimation, AI-generated image detection, face detection and recognition, OCR, depth, and segmentation attach to the same call, so a warehouse check that needs OCR on a shipping label and a segmentation mask on a damage photo does not require a second model pipeline with its own latency, cost, and failure modes. That combination — calibrated confidence, tight latency, and a schema fixed in code — is what a decision api is supposed to deliver, and it is the design center at DecisionNode.

Replacing Rule Trees and Prompt Chains in Production Workflows

Most teams arrive at a decision API from one of two directions. The first is a rule engine that has grown into a liability: hundreds of hand-written conditions, each added to fix a specific complaint, none of them tested together, and a codebase where no one can explain why a particular account was flagged. The second is a chat-LLM integration wrapped in JSON parsing, schema validators, and retry logic, where a single malformed response can stall an ingestion queue.

A typed decision endpoint sits between those extremes. The questions are still authored by developers, so intent stays explicit, but the mapping from messy input to answer is learned rather than enumerated. Practical entry points include ticket routing and triage, fraud and promo-abuse checks, order and shipping decisions, content moderation, scoring and gating, quality control on production lines, and warehouse or traffic monitoring. In each case the useful pattern is the same: act above a confidence threshold, re-check or take a safe path below it. Low-confidence moderation calls go to a human reviewer. Low-confidence shipping decisions fall back to the previous carrier. Low-confidence fraud checks hold the order for a beat instead of releasing it. The threshold becomes a tunable operational dial rather than a hidden constant buried in a prompt.

The same primitive is a natural fit for AI agents that need to decide before acting. An agent about to click, refund, escalate, or dispatch can make a typed decision call first and branch on the result, rather than generating a paragraph of reasoning and hoping the next tool call is consistent with it. SDKs for TypeScript, Python, Go, Ruby, and curl keep that call small in any stack, while MCP tools and webhooks let the same decision surface inside agent frameworks and event-driven pipelines without bespoke glue code.

Operations teams get something they rarely have with generative systems: an auditable record of what was asked, what state was supplied, what was returned, and how confident the system was at the time. That record is what makes it possible to move a threshold, retrain, or roll back with evidence instead of instinct.

Worked Scenarios: Three Decision Loops in Practice

Support triage at scale. A helpdesk ingests thousands of tickets an hour across email, chat, and an in-app form. Instead of a classifier per queue, the intake service sends the ticket body as text plus account metadata as JSON, and asks three questions in one call: a choice over roughly forty queue labels, a score for urgency, and a truth question for whether the message is a billing dispute. Anything above 0.95 on the queue choice routes automatically; everything else lands in a review lane with the confidence attached. The behavioural change is not just accuracy — it is that a threshold can be raised or lowered per queue during a busy week without touching a prompt.

Promo abuse and refund review. A commerce platform attaches evidence rather than descriptions of evidence: a screenshot of a receipt, a photo of a damaged item, a frame from a delivery scan. The decision call returns a truth value for “is this claim consistent with the attached evidence” plus a confidence, and low-confidence claims are held for manual review with the reasoning already narrowed. Because the same endpoint accepts up to sixteen images or frames, multi-photo claims stay in a single request instead of fanning out across services.

Production-line quality control. A camera station inspects parts as they pass. The call returns box coordinates for suspected defects and a truth value for whether the part should be rejected, and a WebSocket session keeps decisions inside the line’s cycle time well above ten per second. Segmentation and depth boosters sharpen the same request, and because the answers are deterministic, a rejected batch can be re-examined with the exact inputs that produced the decision. Traffic monitoring and warehouse checks follow the same shape: frames in, typed locations and gated decisions out, confidence deciding what a human ever needs to look at.