Decision API: Turning Ambiguous Input Into Typed Decisions Your Code Can Actually Act On

Most production systems do not fail because a model was wrong. They fail because the model’s output was unusable — a paragraph of prose where a database column was expected, a “reply in JSON” prompt that drifted one field to the left after a vendor update, or a confidence signal that was never calibrated in the first place. Teams end up writing three layers of validation, retry, and fallback code around a component that was supposed to save them work.

A decision API takes a different approach. Instead of asking a model to write something and then parsing it, you declare the decision itself in code — the labels, the ordered scale, the threshold, the schema — send the current state as input, and receive a typed answer that already conforms to your contract. The question is fixed at request time; the model’s job is to pick, score, or estimate, not to narrate. For developers, product teams, and ops engineers, that distinction is the difference between an integration you maintain forever and an endpoint you call and forget.

What a Decision API Actually Returns — and Why Typed Output Changes Your Code

The interface is deliberately narrow. A client sends a POST request to a single HTTPS endpoint — on DecisionNode that is /v1/decide — carrying two things: the state (free text, a JSON object, or up to 16 images or video frames) and the questions, defined in code rather than improvised in a prompt string. The response is a set of typed answers produced in one pass, with no multi-turn chaining and no post-hoc parsing step.

The answer types map to the primitives engineers already build systems around. A choice returns exactly one of your labels — priority_support, billing, refund_request — so it can be used directly as a routing key or an enum column. A score returns a level on an ordered scale you defined, which is what you actually want for severity, risk tiers, or quality grades. A truth returns a calibrated probability between 0.00 and 1.00, which is the only form of confidence you can safely compare against a threshold. A number returns a value on a grid, useful for quantities and counts. And point and box return coordinates inside an image, which turns a vision question into structured geometry rather than a caption.

Two properties matter more than the type list itself. First, every answer carries a calibrated confidence, so the calling code can branch on it: act immediately above your threshold, re-check or take a safe path below it. Second, the engine is deterministic — the same request produces the same answer. That single property is what makes a decision layer testable, replayable in incident reviews, and safe to run in shadow mode alongside a legacy rules engine. Compare that with a chat-style model whose temperature, prompt length, and system message all shift the output distribution, and where the failure mode is not a wrong value but an unparseable one.

Contract-first design also changes how the rest of the system is built. Because the schema is declared in code, downstream consumers — queue workers, feature flags, database writes, audit logs — can be generated or validated against it, and the response shape never needs a defensive try/parse/except sandwich. If you want a concrete reference for this pattern, a decision api built around a single endpoint with declared questions and typed responses is the cleanest illustration: the model returns a decision, not a paragraph about a decision.

Latency, Cost, and Confidence Thresholds: Engineering the Decision Loop

Once output is typed and confidence is calibrated, the integration becomes a control-loop problem rather than an NLP problem. The standard pattern is threshold gating. A request comes in, the decision engine returns a truth probability of, say, 0.94 for “this ticket is a chargeback dispute.” Your code routes it automatically. At 0.71 it goes to a human review queue with the probability attached. At 0.40 it follows a known-safe path — acknowledge, gather more context, escalate on a timer. Every branch is explicit, every threshold is a configuration value, and every decision is logged with the number that drove it. That is a system an ops team can tune without redeploying model prompts.

For that loop to run inline rather than asynchronously, latency has to be small enough to disappear into the request budget. DecisionNode publishes two model tiers: Flash at roughly 5 ms server-side and 19 ms end to end, and MoE at roughly 9 ms server-side. Pricing is input-oriented — about $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 and low-volume services. At those numbers, the economics shift: it becomes reasonable to evaluate every ticket, order, or frame instead of sampling a fraction of traffic, and to compare the per-decision cost against the cost of maintaining hand-written rules that nobody remembers the origin of.

Throughput has its own design consideration. Request-response calls are the right shape for most web backends, but control loops that exceed roughly 10 decisions per second — drone flight logic, robot manipulation, simulators, continuous machine monitoring — need a persistent channel, which is why DecisionNode offers sessions over WebSocket for high-frequency loops. Language support is broad by design: SDKs for TypeScript, Python, Go, and Ruby, plus plain curl, MCP tools, webhooks, and first-class support for AI agents that call the endpoint to decide before acting rather than acting and hoping.

The practical benefit of low latency plus determinism is that you can run policy experiments safely. Send production traffic to both the old rule engine and the new decision policy, diff the outputs, and only cut over when the disagreements are ones you can explain. No prompt-tuning folklore, no “it worked in staging.”

Where Decision APIs Earn Their Keep: Triage, Fraud, Moderation, and the Production Floor

The highest-value deployments share a shape: high volume, a small set of meaningful outcomes, and a real cost to both false positives and false negatives. Ticket routing and triage is the canonical case — a choice for the queue, a score for priority, and a truth probability for “does this need a human within the hour,” all returned in one call so the ticketing system can assign before the user’s page finishes rendering.

Fraud and promo-abuse checks lean on calibrated probability rather than binary flags. An order that scores 0.97 on abuse signals can be blocked instantly; one at 0.6 can be held for manual review without frustrating a legitimate customer. The same gating pattern applies to order and shipping decisions, content moderation, risk scoring, and feature gating — anywhere a brittle threshold tree currently encodes years of accumulated exceptions. Quality control on production lines uses a different output type entirely: a box or point over a camera frame identifies where a defect sits, while a choice classifies it, so the line controller can reject, rework, or pass without a separate vision pipeline. Warehouse and traffic monitoring follow the same pattern at scale.

Raw media often needs interpretation before it can be judged, which is where DecisionNode’s boosters matter: human age estimation, AI-generated image detection, face detection and recognition, OCR, and depth or segmentation. These run as part of the decision request, so a document-classification question can rely on OCR output and an identity-check question can rely on face detection without the caller orchestrating three vendors. In practice a single endpoint replaces a chain of preprocessing services, and the caller still receives one typed answer with one confidence value.

For AI agent builders, the appeal is different but equally concrete. An agent that must choose between refunding a customer, escalating, or refusing is making an irreversible decision with a language model’s judgment as its only guardrail. Pointing that step at a decision endpoint with a declared choice set and a calibrated threshold gives the agent a bounded action space and a numeric reason to stop — and gives the team an audit trail of exactly which probability triggered which action.