Decision API: Turning Messy Inputs Into Typed Answers Your Code Can Actually Trust
Most teams introduce AI to a product the same way: they call a chat model, hand it a prompt that pleads for “valid JSON only,” and wrap the response in a try/catch. It demos beautifully and then quietly breaks — a stray sentence before the opening brace, a label that isn’t in your enum, a confidence score of “high” where your code expected a float. The model was never the problem. The interface was. You asked a generative system to behave like a typed function, and every production incident since has been the gap between those two things.
A decision API closes that gap by inverting the design. Instead of generating text and hoping it parses, you send state and a set of questions your code already understands, and you get back schema-valid, typed answers with calibrated confidence attached — in one pass, with no retry loop and no prompt archaeology. For developers, product teams, and ops engineers, that difference is the line between a prototype and a system you can put behind a checkout button.
What a Decision API Is — and What It Isn’t
A decision API is a single HTTPS endpoint whose contract is narrow on purpose. You POST state — raw text, structured JSON, or up to 16 images or video frames — together with questions declared in your code. The service answers them in one request. Crucially, the answers are not prose. They are types: a choice (exactly one of the labels you supplied), a score (a level on an ordered scale you defined), a truth (a calibrated probability between 0.00 and 1.00), a number (a value constrained to a grid), and point or box (locations within an image). Every one of those values is schema-valid by construction, so your downstream code branches on data rather than reparsing a string.
That is the architecture DecisionNode builds around: a “System One” decision model that returns typed, calibrated decisions instead of generated text. Requests land on one endpoint, POST /v1/decide, and come back in a single pass. You can reach it with the SDKs for TypeScript, Python, Go, Ruby, or plain curl.
It’s worth being precise about what this is not. It isn’t a chat completion with a JSON mode toggle. Generative “reply in JSON” calls are non-deterministic by default, charge you for output tokens, and treat the schema as a suggestion the model may drift away from as the prompt grows. A decision API treats the schema as the interface itself: the labels, scales, and answer types are inputs you control, and the model’s only job is to resolve them correctly against the state you sent. Because the same request produces the same answer, you get something rarer than accuracy in AI systems — reproducibility. You can build a golden dataset, diff two model versions, replay last week’s traffic, and write assertions in CI that don’t flake.
The practical consequence is that the awkward middle disappears. There’s no “did it return valid JSON this time?” branch, no second call to reformat, no regex extracting a number out of a sentence. The endpoint either answers your questions or fails loudly at the transport layer, and everything above that line is ordinary application code.
The Contract Is the Prompt: Typed Outputs and Calibrated Confidence
In a decision API, the prompt stops being an English paragraph and becomes a declaration. You define your labels, your ordered scale, your numeric grid, your question text — in code, versioned alongside the service that consumes them. This shifts the design conversation in a healthy direction: instead of asking “how do I phrase this so the model behaves?”, you ask “what are the exact decisions this system is allowed to make?” That question has a right answer, and it usually comes from the product or ops team rather than from whoever happens to be tuning prompts this sprint.
The second half of the contract is confidence. Every answer arrives with a calibrated confidence value, which means a reported 0.85 corresponds to roughly an 85% empirical hit rate over many decisions — not a vibe, not a self-assessment. Calibration is what makes thresholds usable in production:
Above the threshold — say a promo-abuse truth of 0.94 — code acts instantly, no human in the loop. Below it — 0.61, or anything under your ceiling — the request takes a safe path: hold the order, flag for review, ask for a second signal, or route to a person. In the band between — 0.72 to 0.94 — you might auto-approve the low-risk cohort and escalate only the ambiguous slice. The result is a system that fails gracefully by design rather than flipping a coin at the edge of its competence.
This is the layer where DecisionNode earns its place in an architecture. The decision api returns typed answers plus calibration on the same response object, so a single call can drive a hard gate and a soft signal simultaneously. It also exposes boosters — human age estimation, AI-generated image detection, face detection and recognition, OCR, depth and segmentation — that attach to the same request, which matters when a moderation or KYC decision needs both a label and a bounding box from the same frame. Point and box outputs let you answer localization questions with coordinates instead of a paragraph describing where the object probably is.
One design caution: keep labels mutually exclusive and scales genuinely ordered. The model will respect the structure you declare, so a sloppy declaration produces consistent nonsense. Version your question sets the way you version API schemas, and re-run your golden set whenever you change them.
Latency, Throughput, and Where Decision Loops Actually Run
Decision APIs live or die on the latency budget of the loop they sit inside. A pre-checkout fraud gate has tens of milliseconds; a production-line inspection camera has less. DecisionNode publishes two models that map cleanly onto that spread. DecisionNode Flash runs at roughly 5 ms server-side and about 19 ms end-to-end, priced at $0.035 per 1M input tokens — the default choice for interactive request paths. DecisionNode MoE lands around 9 ms at $0.042 per 1M input tokens, for cases where a richer model earns its extra few milliseconds. Output tokens are always free, which is a meaningful difference from generation-based pipelines where verbose reasoning is billed by the paragraph. Batch discounts exist for offline scoring, and there’s a free daily tier for development.
For high-frequency loops, a per-request HTTPS call stops being the right shape. Sessions over WebSocket are designed for anything above roughly 10 decisions per second — drone and robot control, simulators, machine monitoring — where a persistent channel avoids per-call overhead. Webhooks and MCP tools cover the async and agent-integration cases respectively, letting an AI agent decide before acting rather than narrating a plan and hoping the next step lands.
Concrete loops tend to cluster into recognizable patterns. A support platform posts a ticket body and asks for a choice across routing labels plus a score for urgency — one call instead of a rules tree maintained by four teams. A payments team asks for a truth on promo abuse and a choice between approve, review, and block, then lets the calibration value decide which branch fires. A warehouse monitoring pipeline sends frames and asks for a point at the location of a mislabeled pallet, gating the answer on confidence before alerting a supervisor. A quality-control station on a production line uses box outputs to flag defects on a moving conveyor, with the calibration threshold tuned per line so false positives don’t overwhelm the operators.
In every one of those cases, the engineering work is the same: declare the questions, pick a threshold, wire the high-confidence path to automation and the low-confidence path to a human or a safe fallback. The model is fast enough to sit inline, deterministic enough to test, and typed enough that the response slots straight into the code that already exists.
Lyon food scientist stationed on a research vessel circling Antarctica. Elodie documents polar microbiomes, zero-waste galley hacks, and the psychology of cabin fever. She knits penguin plushies for crew morale and edits articles during ice-watch shifts.
