Almost every team that adds intelligence to a product starts the same way: wrap a chat model, write a prompt that ends with “respond only in JSON,” and parse the result. It demos beautifully. Then production happens — truncated payloads, invented labels, fields that appear three calls out of a hundred, latency that swings by seconds, and a validation layer held together with regex and optimism. A decision API removes that whole class of failure by changing the contract. Instead of asking a model to talk and hoping the shape survives, you declare the questions in code and receive typed, schema-valid answers that your application can act on immediately.
What a Decision API Is, and Why the Contract Matters More Than the Model
A decision API is an HTTP interface that takes state — raw text, structured JSON, or a batch of up to 16 images and video frames — together with a set of questions you define in code, and returns answers in a fixed, validated schema. The important part is that the response is not prose to be parsed; it is a value of a declared type. There is no ambiguity about which label was chosen, no need for a repair prompt, and no drift in format when the underlying model changes.
In practice, a well-designed decision API exposes a small, closed set of answer types that cover most operational questions. A choice returns exactly one label from a set you supply — billing, shipping, account access — and never an invented fourth option. A score places the input on an ordered scale, so “how risky” becomes a discrete level rather than a paragraph of hedging. A truth returns a calibrated probability between 0.00 and 1.00, which is the primitive you actually want for gating and prioritization. A number returns a value snapped to a grid, useful for quantities and measurements. Point and box answers return spatial locations inside an image, which is what makes visual decisions programmable.
The second half of the contract is confidence. Every answer arrives with a calibrated confidence value, which lets application code implement a threshold policy that is genuinely simple: above the threshold, act immediately and inline; below it, re-check, escalate to a human, or take a safe default path. That single pattern replaces an enormous amount of defensive glue code, because the uncertainty is expressed as a number instead of being buried in natural language.
Determinism is the third pillar and the one teams underestimate. When the same request returns the same answer, you can write unit tests against decision logic, replay a production incident byte-for-byte, and run regression suites before changing thresholds. Systems built on sampled generation cannot offer that, and the resulting fear of touching the prompt is a real delivery cost. A decision API makes the decision layer behave like software rather than like weather.
Inside the Request/Response Loop: State In, Schema Out, and the Latency Budget
The interaction model is deliberately boring, which is the point. You send a single HTTPS request — POST /v1/decide — carrying the state and the questions, and you get schema-valid typed answers back in one pass. There is no multi-turn negotiation, no chain of intermediate prompts to debug, and no second call to coerce the output into the right shape. For teams that have been maintaining a “reply in JSON” pipeline with retries and fallbacks, collapsing that into one round trip removes most of the moving parts.
Latency economics decide where the API can live architecturally. DecisionNode’s Flash model runs at roughly 5 ms server-side and 19 ms end to end, while the MoE model runs at about 9 ms. Both are priced per input token — $0.035 per 1M input tokens for Flash and $0.042 per 1M for MoE — with output tokens always free, batch discounts available, and a free daily tier for development. What that means practically is that decisions can sit inline on the request path, not just in an async batch job. A support ticket can be routed before the page renders. A promo code can be checked before the order confirms. A frame can be classified within a control loop’s tolerance.
Calibration is what turns those numbers into policy. If a truth answer says 0.86 that a ticket requires human escalation, then across many such tickets roughly 86 percent should be escalation cases — and that property is what justifies hard-coding a threshold of, say, 0.90 for auto-routing. Teams evaluating this pattern can inspect the request shape, the answer types, and the SDK surface for the decision api to see how the schema is expressed in code rather than in prose.
The integration surface matters for adoption speed. Client libraries exist for TypeScript, Python, Go, Ruby, and plain curl, alongside MCP tools and webhooks for agent and automation workflows. In a typical service, that means a typed client method replaces a prompt string, and a discriminated union in your own codebase replaces a parsing function — the decision layer becomes a dependency you can mock, version, and test.
Architecture Patterns and Where a Decision API Actually Pays Off
The simplest pattern is a synchronous gate: one call per user action, one typed answer, one threshold. Ticket routing and triage fits here — a choice answer picks the queue, a truth answer flags escalation risk, and confidence decides whether the ticket is auto-routed or parked for a human. The same shape covers moderation, eligibility gating, and order and shipping decisions where a wrong guess is expensive but a slow guess is worse.
A second pattern is the decision loop. Sessions over WebSocket exist specifically because some workloads exceed roughly ten decisions per second — drones, robots, simulators, and machine monitoring on a production line. In these systems the state arrives continuously, the threshold policy runs in the control loop, and confidence below the threshold triggers a conservative action rather than a stall. The result is control logic that reads like ordinary code with a probability attached to each branch.
A third pattern is the agent pattern: decide before acting. Rather than letting an autonomous agent call a tool and then judge the outcome, the agent calls a decision endpoint first, receives a typed verdict and a confidence, and only proceeds above threshold. MCP tooling and webhooks make this composable with existing agent frameworks, and the deterministic response makes agent traces reproducible — a meaningful advantage when an agent misbehaves in production and someone has to explain why.
Specialized boosters extend the same contract into harder inputs. Human age estimation, AI-generated image detection, face detection and recognition, OCR, and depth and segmentation turn image and frame payloads into the same typed answers as text, which is what makes quality control on production lines, warehouse monitoring, and traffic monitoring tractable with one API rather than three vendors. The migration path that teams report most value from is replacing hand-written rule tables with calibrated scores while keeping the old rules as the below-threshold fallback — a hybrid that ships in weeks. From there, log every request with a state hash, the answer, and its confidence; the borderline band between roughly 0.4 and 0.6 becomes your highest-value labeled dataset, and each review pass tightens the thresholds until the safe path is the exception rather than the norm.
