A decision API is an HTTP endpoint that accepts a representation of state — text, structured JSON, or a handful of images — along with a set of questions defined in code, and returns a structured answer your program can branch on without parsing prose, guessing at shape, or retrying. It is not a chat model with a JSON mode bolted on. The distinction matters because the two fail in completely different ways, and only one of those failure modes is survivable in a production request path.
What a Decision API Actually Does (And Why a Chat LLM Is Not One)
Most teams that need machine judgment today reach for a general-purpose chat model and ask it to “reply in JSON.” It works in a demo. In production it produces markdown fences around the payload, invents a field that wasn’t in the schema, returns a confidence-free string like “likely,” or contradicts itself on an identical input ten seconds later. You end up writing a validator, a repair loop, and a fallback path — and the fallback path is where the real cost hides, because it means the model’s output is not actually driving the decision, your error handling is.
A decision API inverts that contract. Instead of generating text and hoping it conforms, it returns typed, schema-valid answers in a single pass. The vocabulary is deliberately small and covers almost every decision an application actually makes:
choice — one label from a set you supply (routing destination, category, approve/deny). score — a level on an ordered scale (risk tier, priority, severity). truth — a calibrated probability between 0.00 and 1.00. number — a value on a defined grid (quantity, count, adjustment). point and box — locations within an image, for anything visual.
That list is the whole interface, and its narrowness is the feature. When the answer type is choice, there are no malformed answers — there is only the set of labels you declared. When the answer type is truth, you get a float you can compare against a threshold instead of an adjective you have to interpret.
DecisionNode implements this as a single HTTPS endpoint, POST /v1/decide, where you send state plus the questions you’ve defined in code and receive every answer back in one round trip. The state can be text, JSON, or up to 16 images or video frames, so the same call shape covers a support ticket, an order record, and a photo from a production line. Because the system is built as a “System One” decision model rather than a generative one — it returns decisions, not text — it is also deterministic: the same request returns the same answer. That property is underrated. It means decision logic is unit-testable, replayable from a logged request fixture, and reviewable in a pull request the same way any other pure function is.
The practical consequence for engineers is that the call site stops looking like a special case. A decision API becomes just another dependency with a schema, a timeout, and a documented response type — not an unpredictable subsystem that requires its own observability stack and its own on-call runbook.
Calibrated Confidence Is the Actual Product
The typed answer is the visible half of a decision API. The half that changes architecture is the calibrated confidence attached to every response. Calibration means the number means what it says: when the system reports 0.90, roughly nine out of ten such predictions are correct. An uncalibrated score — the raw logit, the softmax maximum, the vibe-based “confidence” many wrappers expose — lets you set a threshold that looks reasonable and is silently wrong.
Once confidence is trustworthy, decision logic becomes an explicit two-band policy instead of a guess:
Above the threshold: the code acts immediately, with no human in the loop and no second model call. Below the threshold: the code takes a defined safe path — escalate to a queue, request additional evidence, fall back to a deterministic rule, or hold the item for review.
This is how you get automation coverage without unbounded error rates. The threshold is a tunable, auditable number in configuration, and the distribution of confidences is a monitoring signal: a shift in the share of low-confidence answers is an early warning that inputs have drifted, long before anyone files a bug.
Latency and cost decide whether that logic can sit inline. DecisionNode ships two models: DecisionNode Flash at roughly 5 ms server-side and 19 ms end to end at $0.035 per 1M input tokens, and DecisionNode MoE at roughly 9 ms and $0.042 per 1M input tokens. Output tokens are always free, there is a free daily tier for development, and batch discounts apply to bulk work. For workloads that need to decide in a tight loop — drones, robots, simulators, machine monitoring — the same engine is available over WebSocket sessions rather than one-shot requests, which matters above roughly 10 decisions per second.
Integration surface is intentionally boring: SDKs for TypeScript, Python, Go, and Ruby, plus plain curl, MCP tools, webhooks, and support for AI agents that need to decide before acting rather than after generating a plan. A single decision call is often cheaper than the tokens an agent would spend deliberating in text.
Where Decision APIs Replace Hand-Written Rules and Where They Don’t
Rule engines fail in a specific, recognizable way: the rule set accretes. Someone adds an exception for a regional carrier, someone patches a promo-abuse check after an incident, and eighteen months later nobody can delete a branch because nobody can prove it’s dead. Decision APIs don’t eliminate rules — they move the judgment out of the branch tree and into a declared question, where the answer is a typed value your existing code still owns.
The patterns that map cleanly are the ones where a human would glance at the input and instantly know the answer, yet the written rules are long: ticket routing and triage (choice across your queue labels, score for priority), fraud and promo-abuse checks (truth against a review threshold), order and shipping decisions, moderation, scoring and gating, and quality control on production lines. Warehouse and traffic monitoring lean on the image side of the API, where point and box answers locate something in a frame rather than merely classifying it. Where the base model needs domain help, boosters cover human age estimation, AI-generated image detection, face detection and recognition, OCR, depth, and segmentation — each one turning a hard sub-problem into a field on the response.
The migration path that avoids a big-bang rewrite is shadow mode. Run the decision call alongside the existing rules on live traffic, log both outputs and the confidence attached to each, and compare. Because answers are deterministic, a disagreement is reproducible from the logged request — not a heisenbug. Tune the threshold against real data, then cut over one decision at a time, keeping the deterministic rule as the documented fallback for the low-confidence band. A fair evaluation costs little: a thin client against decisionnode.com is enough to run a shadow comparison, and the free daily tier plus batch discounts mean the side-by-side can cover full production volume rather than a sample.
What to avoid is treating the decision API as an oracle for questions your product hasn’t defined. If nobody can state the labels, the ordered scale, or the action that follows each answer, the model is being asked to invent policy — and no amount of calibration fixes an undefined question. The teams that get the most from this pattern are the ones that arrive with a schema, a threshold, and a named human who owns the low-confidence queue.
Helsinki game-theory professor house-boating on the Thames. Eero dissects esports economics, British canal wildlife, and cold-brew chemistry. He programs retro text adventures aboard a floating study lined with LED mood lights.