# DecisionNode

> A decision model and the inference API that serves it. Send text, JSON or images and get a typed choice, a score or the probability that a statement is true, calibrated, in milliseconds, from our own GPUs.

DecisionNode is one HTTPS endpoint, `POST https://api.decisionnode.com/v1/decide`, that reads a state (text, JSON or images) and answers typed questions: a choice among options, a score on a scale, the probability that a statement is true, or a number. Every answer carries calibrated probabilities. It never generates text. Made by Bynn Intelligence, Inc.

## For coding agents: the integration contract

The block below is the same prompt the documentation hands to coding agents (https://decisionnode.com/docs/coding-agents). Follow it as written; it is the API contract.

You are adding DecisionNode to this codebase. DecisionNode is a decision API: it reads a state (text, JSON or images) and answers typed questions with calibrated probabilities. It never generates text.

Endpoint: POST https://api.decisionnode.com/v1/decide
Auth: header "Authorization: Bearer <key>", key read from the DECISIONNODE_API_KEY environment variable on the server. Never ship the key to a browser or log it.

Request body (model and questions required, state and images optional):
{
  "model": "decisionnode-latest",  // or "decisionnode-flash-latest"
  "state": "<text>" | { ...json },
  "images": [{ "id": "photo", "media_type": "image/jpeg", "data": "<base64>" }],
  "questions": {
    "<key>": { "type": "choice", "instructions": "...",
      "criteria": { "<option>": "<what it means>" } },
    "<key>": { "type": "score", "instructions": "...",
      "criteria": ["<lowest>", "...", "<highest>"] },
    "<key>": { "type": "truth", "instructions": "<a statement to test>" },
    "<key>": { "type": "number", "instructions": "<what to count or read>",
      "min": 0, "max": 50 }
  }
}

Response:
{ "model", "answers": { "<key>": answer },
  "usage": { "input_tokens", "output_tokens": 0 } }
- choice: { "choice": "<one of your option keys>", "confidence", "probabilities" }
- score:  { "score": <expected level index>, "confidence", "legend", "probabilities" }
- truth:  { "truth": <probability the statement is true, 0.00 to 1.00> }
- number: { "number": <most probable grid value>, "expected", "confidence", "probabilities" }

Rules for the integration:
1. Ask every question about one input in one request; the state is read once.
2. Branch on confidence (choice, score) or on the truth probability. Keep the thresholds in config, not inline. Above a threshold act at once; below it take a safe automatic action (hold, decline, or re-check with the full model).
3. On 429 wait for the Retry-After header, on 529 retry with exponential backoff and jitter. Do not retry 401, 403 or 422; fix the key or the body.
4. Pin a version such as "decisionnode-1.0" where answers must not change across releases.
5. Write a test that posts a fixed request and asserts the answer keys and types.

## Key facts

- API base: https://api.decisionnode.com. Endpoints: `POST /v1/decide` (ask questions), `GET /v1/models` (https://api.decisionnode.com/v1/models).
- Authentication: `Authorization: Bearer <key>`; keys start with `dn_live_` and are created in the console at https://decisionnode.com/console/keys. Keep the key in the `DECISIONNODE_API_KEY` environment variable on a server, never in a browser.
- Models: `decisionnode-latest` (DecisionNode-1.0, pinned version `decisionnode-1.0`, $0.042 per million input tokens, $0.021 as a batch job) and `decisionnode-flash-latest` (DecisionNode-1.0 Flash, pinned version `decisionnode-1.0-flash`, $0.021 per million input tokens, $0.0105 as a batch job). Output tokens are free: the API answers with numbers, not text.
- Limits per request: 64k tokens of context, up to 4 images of 10 MB each, up to 255 options in a choice, up to 10 levels in a score.
- Errors: 401 bad key, 422 bad body (fix, do not retry), 429 over the rate limit (wait `Retry-After`), 529 overloaded (retry with backoff).
- Try it without a key: https://decisionnode.com/playground runs the request shapes against a mock.

## Documentation

### Get started

- [Introduction](https://decisionnode.com/docs): DecisionNode is a decision model and the inference API that serves it. You send text, JSON or images with typed questions and get typed answers back in milliseconds: a choice or a score with calibrated confidence, a Truth (the calibrated probability that a statement is true), or a number on your grid.
- [Quickstart](https://decisionnode.com/docs/quickstart): Get an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, no SDK to install.
- [With coding agents](https://decisionnode.com/docs/coding-agents): DecisionNode is one HTTPS call, so a coding agent can write the integration for you once it knows the shape. Paste the prompt below, or give your own agents a decide tool.
- [Examples](https://decisionnode.com/docs/examples): Complete recipes you can start from: the problem, the request, the answer and the code that branches on it. Each one runs in the playground as is.

### Concepts

- [State](https://decisionnode.com/docs/concepts/state): The state is the thing you are deciding about. It can be any text, a JSON object or a JSON array. It is read once per request and shared by every question.
- [Questions](https://decisionnode.com/docs/concepts/questions): Questions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a Truth (the probability that a statement is true), or a number on your grid.
- [Choice](https://decisionnode.com/docs/concepts/choice): A choice question picks exactly one option from the list you give and returns the probability of every option plus a confidence you can threshold.
- [Score](https://decisionnode.com/docs/concepts/score): A score question places the input on an ordered scale you define. It returns the expected level, the probability of every level and a confidence.
- [Truth](https://decisionnode.com/docs/concepts/truth): Is this statement true? One calibrated probability from 0.00 to 1.00 that the statement is true. 0.80 means true about 8 times in 10. Your code picks the cut-off: 0.50 for a plain yes or no, higher when acting on a false yes is costly. It is the simplest type and the one most gates are built on.
- [Number](https://decisionnode.com/docs/concepts/number): How many, or what value? One value on a grid you set (min, max and an optional step), with a calibrated probability for every value: the most probable value, the expected value and the confidence. A count in a photo, a year in a contract, the overdue invoices in a statement: one call, no text to parse.
- [Images](https://decisionnode.com/docs/concepts/images): Send images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and answers through the same question types: choice, score, truth, and number for counts.
- [Confidence](https://decisionnode.com/docs/concepts/confidence): Probabilities are calibrated per question type, so a threshold means what it says. This page explains what calibrated means and how to choose where to draw the line.
- [Determinism](https://decisionnode.com/docs/concepts/determinism): The same request to the same model version returns the same answer. There is no sampling and no temperature, so answers can be tested, cached and audited.

### Models

- [DecisionNode-1.0](https://decisionnode.com/docs/models/decisionnode): Our most accurate decision model, trained by us and served on our own GPUs. $0.042 per million input tokens, output free.
- [DecisionNode-1.0 Flash](https://decisionnode.com/docs/models/flash): The compact, fastest tier. Same API and answer shapes as DecisionNode-1.0, chosen with the model field, at $0.021 per million input tokens (provisional).
- [Limits](https://decisionnode.com/docs/models/limits): Context size, image limits, question limits and default throughput per workspace. These apply to both models.

### Patterns

- [Confidence-gated routing](https://decisionnode.com/docs/patterns/confidence-gated-routing): Set a threshold once: every answer above it is acted on instantly, and everything below it is re-checked by the full model or takes the safe path. Calibrated confidence makes the split predictable.
- [Fan-out](https://decisionnode.com/docs/patterns/fan-out): Ask many questions about one input in one request, and run many inputs in parallel within your rate limits.
- [Guardrails](https://decisionnode.com/docs/patterns/guardrails): Gate an agent's tool calls: before the agent acts, ask DecisionNode whether the action is safe and in scope, and run it only above your bar.
- [Control loops](https://decisionnode.com/docs/patterns/control-loops): More than 10 decisions a second? Use a session. DecisionNode becomes the decision layer of a drone, a simulator or a monitoring loop: it picks the mode or the next action, and your controller carries it out. (announced, not yet served)

### API reference

- [POST /v1/decide](https://decisionnode.com/docs/api/decide): Answer typed questions about a state and optional images. One request, one buffered JSON response, one answer per question.
- [Sessions](https://decisionnode.com/docs/api/sessions): Streaming decisions. Open a session once with the fixed part of your request, then stream frames over a WebSocket and get a typed decision for each one. More than 10 decisions a second? Use a session. (announced, not yet served)
- [GET /v1/models](https://decisionnode.com/docs/api/models): List the model names your key can send, each with the pinned version it answers from today and its limits.
- [Errors](https://decisionnode.com/docs/api/errors): Every error is a status code plus a JSON body with a detail field. A request succeeds for every question or fails as a whole. Retry 429 and 529, retry 402 once you have added credit, and fix the request for 400, 401, 403 and 422.
- [Rate limits](https://decisionnode.com/docs/api/rate-limits): Limits are per workspace, counted in requests per second and input tokens per second. Over either one, the API answers 429 with Retry-After.

### Pricing and billing

- [Pricing and billing](https://decisionnode.com/docs/pricing): You pay for input tokens only. Output is free because the model generates no text. DecisionNode-1.0 is $0.042 and DecisionNode-1.0 Flash $0.021 (provisional) per million input tokens, from a prepaid balance. Batch jobs cost half.

### Policies

- [Responsible use](https://decisionnode.com/docs/responsible-use): Most decisions can run fully automatically. Decisions about people in a few areas need a qualified person to review each one, a safety check refuses a narrow set of harmful requests, and military use needs a signed addendum. This page says what that means for your code.

### Migrate

- [Coming from a Jev-shaped API](https://decisionnode.com/docs/coming-from-jev): If your code calls the decide API that TypeSafe AI documents for its Jev model, DecisionNode accepts the same request shape and returns the same response shape. This page lists what to change and what differs.

## Other pages

- [Home](https://decisionnode.com): what DecisionNode is and the pricing.
- [Benchmarks](https://decisionnode.com/benchmarks): accuracy, calibration and latency against named alternatives.
- [Examples](https://decisionnode.com/examples): worked integrations.
- [Playground](https://decisionnode.com/playground): the API's request shapes, runnable without a key.


## Full text

- [https://decisionnode.com/llms-full.txt](https://decisionnode.com/llms-full.txt): every documentation page as Markdown, in reading order.