Most teams building automated decisioning today end up in the same place: a prompt that asks a chat model to “reply in JSON,” a fragile parse layer, a schema validator that spits out errors at 2 a.m., and a rule engine held together with feature flags. The results are inconsistent, the latency is unpredictable, and nobody can explain why the model picked label B over label C on a specific request. A decision api inverts that pattern. Instead of generating text and hoping it parses, you send state and questions the model answers directly in a fixed, typed shape — and every answer arrives with a calibrated confidence attached.
What a Decision API Is, and Why It Isn’t an LLM Call in Disguise
At the protocol level, a decision API is deliberately boring. You POST a JSON payload to a single HTTPS endpoint — on DecisionNode, that’s /v1/decide — containing the state the system should reason over and a set of questions defined in code. State can be plain text, structured JSON, or up to 16 images or video frames. The response is not prose. It is a schema-valid, typed answer: a choice from a label set you supplied, a score on an ordered scale you defined, a truth expressed as a calibrated probability between 0.00 and 1.00, a number snapped to a grid you specified, or a point or box marking coordinates inside an image. The entire decision returns in a single pass, with no follow-up round trip to format the output.
That distinction matters more than it first appears. When a chat model is coerced into emitting JSON through prompting, three failure modes are baked in. First, format entropy: the model may wrap output in markdown fences, rename a key, or return a string where a boolean was expected, and your downstream code has to defend against every variant. Second, silent overconfidence: a generated answer looks equally authoritative whether the model was near-certain or essentially guessing. Third, cost and latency variance: output tokens cost real money and dominate response time, so throughput becomes a budgeting problem rather than an engineering one.
A typed decision model sidesteps all three. Output tokens are the enum, the float, the coordinate — nothing is generated verbatim, so there is nothing to format. On DecisionNode, output tokens are always free, and the two available models sit in a latency band that makes synchronous decisions viable: DecisionNode Flash runs at roughly 5 ms server-side and 19 ms end to end at $0.035 per 1M input tokens, while DecisionNode MoE runs at about 9 ms at $0.042 per 1M input tokens. Both are deterministic — the same request returns the same answer — which means a decision can be replayed from a logged payload, unit-tested against golden fixtures, and audited months later without wondering whether sampling temperature shifted the outcome.
The subtle but highest-leverage property is calibration. A truth of 0.82 should be right roughly 82% of the time across a large batch. That turns confidence from a vibe into an operational lever: your code acts instantly above a threshold, and re-checks, escalates to a human, or takes a safe path below it. No prompt engineering required — the threshold lives in your service, not in the model’s instructions.
Designing Decision Schemas: Questions in Code, Answers You Can Trust
Because questions are expressed as data structures rather than prose, the schema becomes the contract. A well-designed decision schema has three characteristics: the label set is exhaustive and non-overlapping, the ordered scale has meaningful boundaries, and the numeric grid reflects real business resolution. If a routing decision can only produce Billing, Technical, Account, or Unknown, the schema should say exactly that — never a free-text “category” field that invites a long tail of synonyms your downstream systems can’t switch on.
For ordered scales, resist the temptation to cram too many levels in. A five-step scale like critical / high / medium / low / none is usually more actionable than a hundred-point score, because every level can be tied to a concrete runbook step. Where you genuinely need granularity, use the number type with an explicit grid — say values in increments of 0.05 between 0 and 1 — so downstream arithmetic never has to contend with floating-point surprises from an unconstrained generation.
Spatial answers deserve the same discipline. When you ask for a box, you’re getting coordinates you’ll feed into a crop, a redaction, or a counting pipeline, so define whether coordinates are normalized or pixel-based and validate against image dimensions before acting. Paired with boosters such as face detection, OCR, depth estimation, and segmentation, point and box outputs make it practical to build inspection loops — for example, confirming that a shipping label printed in the correct region of a package — without standing up a separate computer-vision stack.
Two engineering practices pay for themselves immediately. The first is threshold policy in code, not in prompts: keep a per-question configuration object that maps confidence bands to actions (auto-approve, auto-reject, queue for review), and log the band alongside the answer so you can tune it against real outcome data. The second is schema versioning. Treat each question set as a versioned artifact, store the version with every logged decision, and replay old payloads against new schemas in staging before rolling changes out. Determinism makes this cheap: identical requests produce identical answers, so a diff in replay output is always a genuine behavioral change rather than noise.
Finally, keep questions narrow and composable. One request can carry several questions at once, which is often faster and cheaper than chaining calls — a moderation pipeline might ask for a choice (policy category), a truth (is this abusive?), and a score (severity) in a single pass, then branch in application code based on which confidences cleared their thresholds.
Where Decision APIs Earn Their Place: Workflows, Throughput, and Operational Reality
The workloads that benefit most are the ones where a brittle hand-written rule tree has quietly become a maintenance burden. Ticket routing and triage is the canonical example: a rules engine keyed on regex and keyword lists drifts as products rename and customers change vocabulary, while a decision model returns a typed label with a confidence you can gate on. Fraud and promo-abuse checks follow the same shape — a truth score for “is this account likely multi-boxing?” combined with a choice for the suspected abuse pattern gives risk teams both a verdict and a reason to investigate.
Order and shipping decisions benefit from spatial and multimodal inputs specifically. Addressing exceptions, damaged-goods claims with photo evidence, and packing verification all involve images that a text-only rule engine can’t see. Moderation, scoring, and gating workloads benefit from determinism: when a creator appeals a decision, you can replay the exact payload and show the same confidence band that triggered the original action. On production lines, quality control and warehouse or traffic monitoring use cases push volume higher, which is where the sessions over WebSocket transport matters — for loops that exceed roughly 10 decisions per second, as with drones, robots, simulators, and continuous machine monitoring, a persistent session avoids per-request connection overhead while preserving the same typed answer contract.
Integration surface is a practical concern for platform teams. DecisionNode ships SDKs for TypeScript, Python, Go, Ruby, and curl, plus MCP tools and webhooks, so the same decision logic can be called from a Go microservice, a Python batch job, and an AI agent reasoning step. That last case is worth emphasizing: an agent that “decides before acting” — checking a calibrated truth above 0.9 before executing a tool call — is materially safer than one that generates a plan and self-assesses its own confidence in prose.
Cost modeling is straightforward in a way that generative workloads rarely are. Input tokens are metered at the published per-million rate, output tokens are free, batch discounts are available for offline scoring, and there’s a free daily tier for development and low-volume production checks. For ops teams replacing a rules engine, the migration path is incremental: shadow the existing rules with decision calls, log both outputs, and compare agreement rates before cutting over. Where they disagree, you’ve found the edge cases the rules engine was silently mishandling — which is usually the argument that gets the migration funded.
