# Decision API: Shipping Typed, Deterministic Decisions Instead of Parsing Model Prose

Ask most engineering teams how they get a model to make a decision in production, and you’ll hear a familiar story: prompt a chat model to “reply only in JSON,” then wrap the call in a parser, a retry loop, a schema validator, and a fallback branch for the days the model decides to explain itself instead. It works — until it doesn’t. The output drifts, the JSON breaks, the latency spikes, and nobody can reproduce the result that flagged a fraudulent order last Tuesday.

A decision api takes a different stance. Instead of generating text that you hope contains an answer, it accepts state plus a question defined in code and returns a **typed answer** in one pass. The contract is the product: you declare what a valid decision looks like, and the endpoint either satisfies that schema or tells you how confident it is that it did.

## What a Decision API Actually Is

The term gets used loosely, so it’s worth being precise. A decision API is an HTTPS endpoint whose response is a *decision*, not a sentence. That means the outputs are enumerable and machine-actionable rather than freeform prose. In practice, the useful primitives are few:

– **choice** — one label from a set you define (`refund`, `replace`, `reject`, `escalate`)
– **score** — a level on an ordered scale (`low` / `medium` / `high`, or 1–5)
– **truth** — a calibrated probability between 0.00 and 1.00
– **number** — a value constrained to a grid you specify
– **point** and **box** — spatial locations inside an image

That last category is the one teams underestimate. The moment a decision depends on *what’s in a photo* — a damaged box, a mislabeled pallet, a crowd density estimate, a face in an access queue — text-only “LLM with JSON mode” approaches collapse into elaborate prompt engineering. A decision endpoint that accepts up to sixteen images or video frames alongside the question can answer spatial questions natively, returning a box or point rather than a paragraph describing where the thing might be.

The distinction matters most when you move from prototype to production. Generated text has no schema guarantee, no stable latency profile, and no reproducibility. A typed decision has all three, because the model’s job is bounded: classify, rank, score, or localize — not compose. DecisionNode, for example, exposes this as a single `POST /v1/decide` call where you send state (text, JSON, or frames) plus questions defined in code, and receive schema-valid answers carrying a calibrated confidence value alongside the result itself.

That confidence field is the quiet superpower. A bare label forces your code to trust it absolutely. A label plus a calibrated probability lets your code *choose its own risk posture*: act instantly above 0.90, re-check or route to a human below it.

## The Request/Response Loop: State In, Typed Decisions Out

The architecture of a decision API is deliberately boring, which is the point. You send one request; you get one response; there are no multi-turn negotiations, no tool-calling choreography, no “please reformat your previous answer” follow-ups.

The request carries two things: **state** and **questions**. State is whatever the decision depends on — a support ticket body, an order JSON object, a warehouse photo, a sequence of frames from a conveyor camera. Questions are defined in code, not in prompts: you declare which labels are legal, which scale applies, which grid the number must land on, which region of the image is fair game. Because the question set ships with the request as structured data, the same endpoint handles a routing decision and a defect-detection decision without any server-side reconfiguration.

The response is schema-valid by construction. You get your label, your level, your probability, your coordinate — plus a confidence for each. That design choice has downstream consequences that are genuinely useful:

**One pass, not a chain.** There is no orchestration layer to build. You don’t need a planner agent deciding which sub-model to call, because the question definition already does that work.

**Determinism.** Same request, same answer. This is the property that makes a decision API auditable. When a compliance reviewer asks why a specific order was held, you can replay the exact request and get the exact response. Chat-model outputs, even at temperature zero, rarely survive that test across model versions and inference stacks.

**Threshold logic in your language.** Calibration means a 0.80 really does correspond to roughly an 80% hit rate across the population — which means your threshold is a business parameter, not a guess. Fraud teams can set 0.95 and accept more manual review; moderation teams can set 0.70 and accept a small false-positive rate in exchange for speed. The API returns the number; *you* own the policy.

For high-frequency loops — robotics, simulators, machine monitoring, drone telemetry — the same contract is available over WebSocket sessions, which sidesteps per-request connection overhead once you’re above roughly ten decisions per second.

## Latency, Cost, and the Economics of Deciding Often

Decision APIs get used in places where per-call cost compounds fast: every ticket, every order, every frame, every agent step. Two cost characteristics dominate.

First, **output is usually free or near-free**. Because the response is a small typed object rather than generated prose, there are no output tokens to bill — DecisionNode states that output tokens are always free, which changes the math on high-volume classification. Second, **input pricing is where the lever is**. DecisionNode Flash runs at about $0.035 per 1M input tokens with roughly 5 ms server-side latency and 19 ms end to end; DecisionNode MoE runs at about $0.042 per 1M input tokens with roughly 9 ms server-side. Batch discounts and a free daily tier exist for backfills and evaluation runs.

Those numbers reframe a common design question. Teams often avoid model calls in hot paths because a 400–900 ms round trip is unacceptable inside a checkout flow or a control loop. At single-digit to low-double-digit milliseconds, the call starts to look like a database lookup — something you do inline, not something you queue.

Latency discipline also enables **defensive decisioning**. If a call costs 19 ms, you can afford to make it twice: run a fast primary decision, and when confidence dips below your threshold, immediately invoke a richer check (extra frames, a booster like OCR or face detection, a MoE pass) rather than punting to a human by default. That two-tier pattern — act fast, verify cheaply, escalate rarely — is how mature teams keep automation rates high without letting error rates creep.

## Where Decision APIs Land in Real Systems

The pattern generalizes across surprisingly different domains, because most operational software is secretly a pile of `if` statements that someone wrote once and nobody dares change.

**Support and ops.** Ticket routing and triage is the canonical case: replace a 900-line keyword-rules file with a `choice` over your queue labels plus a confidence, and route low-confidence tickets to a human queue automatically. The rules file stops rotting; the decision becomes measurable.

**Risk and revenue.** Fraud and promo-abuse checks, order and shipping decisions, and gating (should this account see the feature, get the discount, pass the verification step) all reduce to a calibrated probability and a threshold your business owns.

**Physical operations.** Quality control on production lines, warehouse monitoring, and traffic monitoring lean on point and box outputs — defect located, pallet counted, congestion region identified — with frames streamed over WebSocket sessions.

**AI agents.** Agent builders are increasingly inserting a decision call *before* acting: should this tool be invoked, is this plan safe, does this message violate policy. A deterministic, typed verdict is a far better guardrail than asking the same model that wants to act whether it should.

Integration surface matters here too. SDKs for TypeScript, Python, Go, Ruby, and plain curl lower the cost of adoption, while MCP tools and webhooks let agent frameworks and event-driven pipelines consume decisions without bespoke glue. Boosters — human age estimation, AI-generated image detection, face detection and recognition, OCR, depth and segmentation — cover the cases where the decision depends on a specific visual capability rather than general reasoning.

## Designing Good Questions: Labels, Scales, and Safe Paths

The quality of a decision API deployment is mostly determined before the first request, in how questions are specified.

**Keep label sets exhaustive and mutually exclusive.** If `choice` can legitimately be “none of these,” make that an explicit label rather than letting the model guess. Ambiguous label sets produce confident nonsense.

**Use ordered scales where order exists.** A `score` communicates more than a set of unrelated categories, and it lets you apply monotonic threshold logic downstream. Choose the granularity you can actually act on — a five-level scale you use beats a hundred-point scale you don’t.

**Prefer calibrated probability over vibes.** When the business question is “how risky is this,” ask for `truth` and set the threshold in code. This also gives you an evaluation metric that survives contact with reality: bucket predictions by confidence, measure observed frequency, adjust.

**Design the below-threshold path explicitly.** Every decision needs a defined fallback: retry with richer state, escalate to human review, apply a conservative default, or block. Systems that treat low confidence as an error rather than a signal tend to fail loudly in production.

**Test determinism as a feature.** Because the same request returns the same answer, you can snapshot-test decisions in CI the way you snapshot-test serializers. Wire a handful of representative requests into your test suite and fail the build if a decision shifts unexpectedly — that’s a regression test for judgment.

**Localize state, not rules.** Send what the decision actually depends on and nothing else: the ticket text may not need the customer’s full history, and the conveyor frame may not need the whole image. Trimmed state is faster, cheaper, and easier to reason about when someone asks why the system chose what it chose.

Build the questions carefully and the rest of the system stays boring — one endpoint, one schema, one threshold table, and a decision log you can actually defend.