Decision API: Turning Runtime Questions Into Typed, Calibrated Answers

Every production system eventually reaches the same boundary: the point where logic stops being a lookup and starts being a judgment call. Is this support ticket a billing issue or a bug report? Does this order signature look like fraud? Is that unit on the line within tolerance, or has the seal drifted? Teams have historically answered these questions with two imperfect tools — hand-written rules that grow into unmaintainable trees, or a chat model asked to “reply in JSON” and trusted to keep the shape intact.

A decision API sits between those extremes. It treats a decision as a first-class API contract: you send state, you declare the questions in code, and you receive typed answers with calibrated confidence. DecisionNode’s decision api is built around exactly that contract — a single HTTPS endpoint, POST /v1/decide, that returns a decision rather than a paragraph.

What a Decision API Returns, and Why the Schema Matters

The defining difference is output shape. A general-purpose language model answers in text; a decision API answers with a value drawn from a set you defined before the call was ever made. DecisionNode exposes a small, fixed vocabulary of answer types: choice (exactly one label from your list), 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 and box (locations inside an image). Nothing else comes back — no preamble to strip, no hedging sentence to parse, no explanation field that quietly changes format between releases.

Because the question schema lives in your codebase, the model cannot invent a category that your switch statement has never heard of. If you declare four routing labels, the response is one of those four. If you ask for a severity level on a five-point scale, you get a value on that scale, not a value near it. This is what people mean when they call the output schema-valid: it deserializes directly into the types your application already uses, in a single pass, with no retry-on-parse-failure loop wrapped around it.

State handling is deliberately broad so that one endpoint covers many decision domains. A request can carry plain text, structured JSON, or up to sixteen images and video frames alongside the questions. That combination means a quality-control check on a production line, a moderation call on a user-uploaded photo, and a support-ticket triage can all use the same client, the same auth, and the same error semantics. Product teams get fewer integrations to maintain; platform teams get one dependency to instrument, rate-limit, and audit.

The contract also changes how teams reason about validation. Instead of building a post-processing layer that defends against malformed output, engineers spend that effort on the schema itself: which labels are mutually exclusive, which scale is genuinely ordered, which threshold separates “act now” from “look closer.” Those are product decisions, and a decision API pushes them to where they belong — into reviewable code rather than an untested prompt.

Latency, Determinism, and Cost as Design Constraints

For platform engineers, the numbers that decide architecture are rarely benchmark scores. They are the numbers that determine whether a decision can be made inline or has to be queued. DecisionNode Flash resolves a decision at roughly 5 ms server-side and 19 ms end to end; the Mixture-of-Experts model lands around 9 ms. Input tokens are priced at $0.035 and $0.042 per million respectively, output tokens are always free, batch discounts are available, and there is a free daily tier for development and evaluation. Output being free is a small detail with a large consequence: you can return several typed fields per call — a label, a probability, and a confidence — without the response size driving cost.

Determinism is often more important than raw speed. Same request, same answer means a decision can be replayed in a test suite, diffed between releases, and reconstructed during an incident review months later. Teams that have tried to write integration tests against a chat model know the alternative: assertions that pass on Tuesday and fail on Wednesday with no code change to blame. A deterministic contract turns the decision layer into something you can pin, snapshot, and regression-test like any other service.

Every answer also carries a calibrated confidence, which is where the API earns its place in production rather than in a demo. Code can act instantly when confidence sits above a threshold and route to a re-check, a second model, or a human queue when it does not. A fraud screen can auto-decline above 0.95, flag between 0.60 and 0.95, and let the order through below that — all decided in application logic, with the probability exposed rather than hidden behind a boolean.

Throughput is handled by matching the transport to the workload. Standard request-response covers the vast majority of triage, gating, and scoring paths. For loops that exceed ten decisions per second, sessions over WebSocket remove per-call connection overhead — the pattern that matters for drones, robots, simulators, and continuous machine monitoring, where the decision cadence is tied to a control loop rather than a user action. SDKs for TypeScript, Python, Go, and Ruby, plus curl, MCP tools, and webhooks, mean the integration cost is measured in minutes rather than sprints.

Where Decision APIs Replace Rules Engines and Chat LLM Calls

Three deployment patterns recur across teams adopting this model. The first is triage and routing: ticket classification, queue assignment, and priority scoring, where the inputs are messy natural language and the outputs must be one of a fixed set of team labels plus a confidence the router can threshold on. The second is risk and abuse checks — fraud screening, promo-abuse detection, and order or shipping decisions evaluated before a transaction is committed, where a calibrated probability is genuinely more useful than a yes or no. The third is physical and visual operations: quality control on production lines, warehouse and traffic monitoring, and any workflow where frames or images carry the signal.

That third category is where the answer types earn their keep. A quality-control call can return a box around a defect and a choice describing its class in one pass, so downstream code can crop, log, and escalate without a second round trip. Optional boosters — OCR, depth and segmentation, face detection and recognition, human age estimation, and AI-generated image detection — extend the same endpoint into document handling, access checks, and provenance screening without introducing separate vendors for each capability.

AI agent builders use the API differently again: as a gate before action. An agent that is about to send an email, issue a refund, or modify a record can call a decision endpoint with the proposed action and its context, and receive a typed truth value indicating whether the action meets policy — decide before acting, rather than generating a justification afterward. Because webhooks and MCP tools are first-class, the decision becomes a tool the agent calls rather than a rule buried in its system prompt.

The practical consequence for product and ops teams is that the decision layer stops being a bespoke service. Replacing a brittle rules tree usually means deleting code and adding a schema; adjusting a threshold is a configuration change; adding a new label is a pull request to the question definition, not a rewrite of the classifier. The decision stays auditable, the interface stays stable, and the surrounding application keeps owning the only thing it should: what to do with the answer.