# DecisionNode documentation

> 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.

The map of this documentation is https://decisionnode.com/llms.txt. Each page below is headed by its title and URL.

---

# Introduction

Section: Get started · URL: 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.

(Diagram: a state and its questions go into one request; typed answers with probabilities come back.)

## What you send and what comes back

One request carries a `state` (the thing to decide about) and a map of `questions`. The response carries one answer per question, under the same keys, in the shape its type defines. Here is a support message routed, ranked and checked for an automatic refund in one call.

Request:

```json
{
  "model": "decisionnode-flash-latest",
  "state": "Customer: I was charged twice and nobody has replied for 3 days.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Where should this go?",
      "criteria": { "billing": "money", "bug": "broken", "account": "login" }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["routine", "today", "urgent", "critical"]
    },
    "refund": {
      "type": "truth",
      "instructions": "Refund this automatically?"
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0-flash",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
    },
    "urgency": {
      "type": "score",
      "score": 2.31,
      "confidence": 0.47,
      "legend": {
        "0": "routine",
        "1": "today",
        "2": "urgent",
        "3": "critical"
      },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": { "input_tokens": 62, "output_tokens": 0 }
}
```

The model read the message once and answered three questions in one pass. It generated no text, so `output_tokens` is 0 and you pay only for the 62 input tokens. This request goes to DecisionNode-1.0 Flash, about 5 ms server side. A refund in the unsure middle (0.40 to 0.80) is re-checked by the full model, `decisionnode-latest`, as the diagram shows; everything else is settled by the first answer.

## Four question types

Every type names its answer: choice (one of your labels), score (a level on your scale), truth (a probability), number (a value on your grid).

The four question types

| Type | In the API | What it asks | What comes back |
| --- | --- | --- | --- |
| [Choice](https://decisionnode.com/docs/concepts/choice) | `"type": "choice"` | Pick one option from the list you give | `choice` (always one of your keys), `probabilities` per option, `confidence` |
| [Score](https://decisionnode.com/docs/concepts/score) | `"type": "score"` | Place the input on your ordered scale | `score` (expected level), `probabilities` per level, `legend`, `confidence` |
| [Truth](https://decisionnode.com/docs/concepts/truth) | `"type": "truth"` | Is this statement true? | `truth`, one number from 0.00 to 1.00: the probability that the statement is true |
| [Number](https://decisionnode.com/docs/concepts/number) | `"type": "number"` | How many, or what value? | `number` (a value on your grid), `expected`, `confidence`, `probabilities` per value |

**Reading a Truth answer.** 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.

**Reading a Number answer**. 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. Count the cars in a drone frame, read the year off a contract, count the overdue invoices in a statement. See [Number](https://decisionnode.com/docs/concepts/number).

**Streaming decisions** (announced, not yet served). More than 10 decisions a second, for a drone, a simulator or a monitoring loop? Open a [session](https://decisionnode.com/docs/api/sessions): send the context once, stream frames over a WebSocket and get a typed decision for each. [Control loops](https://decisionnode.com/docs/patterns/control-loops) shows where it fits.

## Why a decision model

Rules break on real input: a regex does not know that "charged twice" is a billing problem. A chat model knows, but it writes text you have to parse, and it does not answer the same way twice. DecisionNode is trained to decide, not to write.

- **Always valid.** Every answer has the shape its type defines. A choice is always one of the keys you sent, so there is nothing to parse or repair.
- **Calibrated.** Probabilities are calibrated per question type, so a threshold on confidence means what it says. See [Confidence](https://decisionnode.com/docs/concepts/confidence).
- **Deterministic.** The same request to the same model version returns the same answer. There is no sampling. See [Determinism](https://decisionnode.com/docs/concepts/determinism).
- **State read once.** The state and images are encoded once and shared by every question, so ten questions cost little more than one.

## The model and the machine

We train the models and we run them, on our own inference stack and our own GPUs. There is no third-party API between your request and the answer, so nothing waits in someone else's queue. DecisionNode-1.0 Flash answers a short request in about 5 ms, measured server side in October 2026: fast enough to sit inside every request, every payment and every frame of a robot's loop.

The two models

| Model | Model id | Price per 1M input tokens | Output |
| --- | --- | --- | --- |
| [DecisionNode-1.0](https://decisionnode.com/docs/models/decisionnode) | `decisionnode-latest` | $0.042 | Free |
| [DecisionNode-1.0 Flash](https://decisionnode.com/docs/models/flash) | `decisionnode-flash-latest` | $0.021 (provisional) | Free |

## Start here

- [Quickstart](https://decisionnode.com/docs/quickstart): Get a key, send one request, branch on the answer. Under five minutes.
- [With coding agents](https://decisionnode.com/docs/coding-agents): A prompt to paste into your coding agent and a decide tool for your own agents.
- [Examples](https://decisionnode.com/docs/examples): Complete recipes: support triage, moderation, receipts, listing photos, lead scoring.
- [POST /v1/decide](https://decisionnode.com/docs/api/decide): Every field of the request and the response, headers and errors.

---

# Quickstart

Section: Get started · URL: 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.

1. **Get an API key** Open the [console](https://decisionnode.com/console/keys), go to **API keys** and choose **Create key**. The key is shown once, so copy it straight into your environment. Live keys start with `dn_live_`.

```bash
export DECISIONNODE_API_KEY="dn_live_..."
```

2. **Send your first request** Post a state and your questions to `https://api.decisionnode.com/v1/decide`. This one routes a support message, ranks its urgency and asks whether to refund it automatically.

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": "Customer: I was charged twice and nobody has replied for 3 days.",
      "questions": {
        "route": {
          "type": "choice",
          "instructions": "Where should this go?",
          "criteria": {
            "billing": "money",
            "bug": "broken",
            "account": "login"
          }
        },
        "urgency": {
          "type": "score",
          "instructions": "How urgent is this?",
          "criteria": ["routine", "today", "urgent", "critical"]
        },
        "refund": {
          "type": "truth",
          "instructions": "Refund this automatically?"
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();
```

3. **Read the answers** Each answer comes back under the key you gave its question. The route is `billing` with confidence 0.81, the urgency sits at 2.31 on your 0 to 3 scale, and the refund probability is 0.94. That last one is a [Truth](https://decisionnode.com/docs/concepts/truth) answer: the calibrated probability, from 0.00 to 1.00, that the statement is true, here that this charge should be refunded automatically. 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, as with a refund.

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
    },
    "urgency": {
      "type": "score",
      "score": 2.31,
      "confidence": 0.47,
      "legend": {
        "0": "routine",
        "1": "today",
        "2": "urgent",
        "3": "critical"
      },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": { "input_tokens": 62, "output_tokens": 0 }
}
```

4. **Branch on them** Answers are numbers and keys, so your code acts on them the moment they land. Sure cases go straight through; unsure ones take the safe path, still automatically.

Python:

```python
route = answers["route"]
urgency = answers["urgency"]
refund = answers["refund"]

if refund["truth"] >= 0.8:              # sure: refund now
    issue_refund(ticket)
    reply(ticket, template="refund_issued")
elif route["confidence"] < 0.7:        # unsure: safe path
    reply(ticket, template="ask_for_order_id")
else:                                  # sure: route it
    priority = round(urgency["score"])
    assign(ticket, route["choice"], priority)
```

TypeScript:

```typescript
const { route, urgency, refund } = answers;

if (refund.truth >= 0.8) {             // sure: refund now
  await issueRefund(ticket);
  await reply(ticket, { template: "refund_issued" });
} else if (route.confidence < 0.7) {  // unsure: safe path
  await reply(ticket, { template: "ask_for_order_id" });
} else {                              // sure: route it
  const priority = Math.round(urgency.score);
  await assign(ticket, { queue: route.choice, priority });
}
```

> **No key yet?** The [playground](https://decisionnode.com/playground) runs the same request in the browser, shows the answers as charts and copies the request as curl, Python or TypeScript.

## What just happened

- The model read the state once and answered all three questions in one pass, with `decisionnode-latest`.
- It generated no text: `usage.output_tokens` is always 0, and output is free.
- The request used 62 input tokens. At $0.042 per million, a million of these requests cost about $2.60.
- Up to 64k tokens fit in one request, so the state can be a whole thread or a JSON record.
- Choice, score and truth are three of the four question types. The fourth, [Number](https://decisionnode.com/docs/concepts/number), answers how many or what value, on a grid you set.

## Next steps

- [Write better questions](https://decisionnode.com/docs/concepts/questions): Options, scales and instructions that the model reads well.
- [Gate on confidence](https://decisionnode.com/docs/patterns/confidence-gated-routing): Act above a threshold, re-check the unsure middle with the full model, and take the safe path below it.
- [Add an image](https://decisionnode.com/docs/concepts/images): Receipts, photos and screenshots in the same request.
- [Handle errors](https://decisionnode.com/docs/api/errors): 400 to 529: which to fix, which to retry, and what to do when credit runs out.

---

# With coding agents

Section: Get started · URL: 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.

## A prompt for your coding agent

Paste this into the agent that works in your repository, then tell it what to decide: "route new tickets in `support/inbox.ts` with DecisionNode". It carries the endpoint, the request and response shapes and the rules that keep the integration honest.

**Agent prompt**

```
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.
```

> **Keep it in the repository** Save the prompt next to your code, for example in the agent instructions file your tools read, so every session starts with the same contract. An agent that can fetch URLs gets the same contract, the key facts and a map of these docs from [decisionnode.com/llms.txt](https://decisionnode.com/llms.txt); the whole documentation as Markdown is at [/llms-full.txt](https://decisionnode.com/llms-full.txt).

## Give your agents a decide tool

Agents act on judgments: is this email a refund request, is this command safe to run, does this reply answer the question. Expose DecisionNode as a tool and the agent gets a typed, calibrated answer instead of its own guess. Most agent runtimes accept a tool described with JSON Schema, like this one.

**Tool definition**

```json
{
  "name": "decide",
  "description": "Ask DecisionNode a typed question about some input. Returns a choice, a score or the probability that a statement is true, all calibrated. Use it before acting on a judgment.",
  "input_schema": {
    "type": "object",
    "properties": {
      "state": {
        "type": "string",
        "description": "The text or JSON to decide about"
      },
      "question": {
        "type": "string",
        "description": "What to decide, in one sentence"
      },
      "type": {
        "type": "string",
        "enum": ["choice", "score", "truth"]
      },
      "options": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Options for choice, levels low to high for score"
      }
    },
    "required": ["state", "question", "type"]
  }
}
```

**Tool handler**

```typescript
type DecideInput = {
  state: string;
  question: string;
  type: "choice" | "score" | "truth";
  options?: string[];
};

export async function decide(input: DecideInput, apiKey: string) {
  const criteria =
    input.type === "choice"
      ? Object.fromEntries((input.options ?? []).map((o) => [o, o]))
      : input.type === "score"
        ? input.options
        : undefined;

  const response = await fetch("https://api.decisionnode.com/v1/decide", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "decisionnode-flash-latest",
      state: input.state,
      questions: { answer: { type: input.type, instructions: input.question, criteria } },
    }),
  });
  if (!response.ok) throw new Error(`decide failed: ${response.status}`);
  const { answers } = await response.json();
  return answers.answer; // the typed answer goes back to the agent as the tool result
}
```

## Ask before you act

The most useful place for the tool is right before an agent does something it cannot undo. Pass the proposed action as the state and ask a Truth question; run it only when the probability clears your bar. [Guardrails](https://decisionnode.com/docs/patterns/guardrails) has the full recipe.

---

# Examples

Section: Get started · URL: 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.

> **Run them without a key** Every recipe here is also a card in the [example gallery](https://decisionnode.com/examples), which opens it in the playground with the request filled in.

## Support inbox that routes itself

**Problem:** new tickets land in one pile and wait hours to be sorted. **Build:** one request per ticket picks the queue, ranks urgency and decides whether to refund on the spot.

Request:

```json
{
  "model": "decisionnode-latest",
  "state": "Customer: I was charged twice and nobody has replied for 3 days.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Where should this go?",
      "criteria": { "billing": "money", "bug": "broken", "account": "login" }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["routine", "today", "urgent", "critical"]
    },
    "refund": {
      "type": "truth",
      "instructions": "Refund this automatically?"
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
    },
    "urgency": {
      "type": "score",
      "score": 2.31,
      "confidence": 0.47,
      "legend": {
        "0": "routine",
        "1": "today",
        "2": "urgent",
        "3": "critical"
      },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": { "input_tokens": 62, "output_tokens": 0 }
}
```

**Branch**

```python
a = answers
if a["refund"]["truth"] >= 0.8:
    issue_refund(ticket)
elif a["route"]["confidence"] < 0.7:
    reply(ticket, template="ask_for_order_id")   # the safe path, still automatic
else:
    queues[a["route"]["choice"]].put(ticket, priority=round(a["urgency"]["score"]))
```

## Moderation pipeline

**Problem:** comments need a decision in the time it takes to post them. **Build:** Flash answers three questions per comment; clear cases are published or removed on the spot, and the uncertain middle is shown with limited reach while the full model re-checks it. Here the model is sure the comment pushes buyers off the platform (0.96) even though the action itself is less certain.

Request:

```json
{
  "model": "decisionnode-flash-latest",
  "state": {
    "surface": "listing comments",
    "comment": "DM me on telegram for half price, this seller is a fraud"
  },
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "What should happen to this comment?",
      "criteria": {
        "allow": "fine to show as is",
        "limit": "show it with limited reach for now",
        "remove": "breaks the community rules"
      }
    },
    "off_platform": {
      "type": "truth",
      "instructions": "Is the comment trying to move a buyer off the platform?"
    },
    "toxicity": {
      "type": "score",
      "instructions": "How hostile is the language?",
      "criteria": ["none", "mild", "strong", "severe"]
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0-flash",
  "answers": {
    "action": {
      "type": "choice",
      "choice": "remove",
      "confidence": 0.61,
      "probabilities": { "allow": 0.04, "limit": 0.22, "remove": 0.74 }
    },
    "off_platform": { "type": "truth", "truth": 0.96 },
    "toxicity": {
      "type": "score",
      "score": 1.18,
      "confidence": 0.46,
      "legend": { "0": "none", "1": "mild", "2": "strong", "3": "severe" },
      "probabilities": { "0": 0.18, "1": 0.52, "2": 0.24, "3": 0.06 }
    }
  },
  "usage": { "input_tokens": 94, "output_tokens": 0 }
}
```

**Branch**

```typescript
const { action, off_platform, toxicity } = answers;

if (off_platform.truth >= 0.9 || (action.choice === "remove" && action.confidence >= 0.8)) {
  await removeComment(comment, { reason: off_platform.truth >= 0.9 ? "off_platform" : "rules" });
} else if (action.choice === "allow" && action.confidence >= 0.8 && toxicity.score < 1) {
  await publish(comment);
} else {
  await limitReach(comment); // unsure: the safe action first
  const recheck = await decide({ ...request, model: "decisionnode-latest" });
  if (recheck.action.choice === "remove") await removeComment(comment, { reason: "rules" });
}
```

## Receipt and invoice checker

**Problem:** expense claims arrive with a photo of the receipt and sit unpaid until they are checked. **Build:** send the claim as JSON and the receipt as an image; the model reads the printed total, currency and date and answers against the claim.

Request:

```json
{
  "model": "decisionnode-latest",
  "state": {
    "expense_claim": {
      "amount": 48.2,
      "currency": "EUR",
      "date": "2026-09-28",
      "merchant": "Northside Cafe"
    }
  },
  "images": [
    { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "questions": {
    "matches": {
      "type": "truth",
      "instructions": "Does the receipt image show the same total, currency and date as the claim?"
    },
    "currency": {
      "type": "choice",
      "instructions": "Which currency is printed on the receipt?",
      "criteria": {
        "EUR": "euro",
        "GBP": "pound sterling",
        "USD": "US dollar"
      }
    },
    "legible": {
      "type": "truth",
      "instructions": "Is the total on the receipt clearly legible?"
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "matches": { "type": "truth", "truth": 0.91 },
    "currency": {
      "type": "choice",
      "choice": "EUR",
      "confidence": 0.91,
      "probabilities": { "EUR": 0.94, "GBP": 0.04, "USD": 0.02 }
    },
    "legible": { "type": "truth", "truth": 0.97 }
  },
  "usage": { "input_tokens": 1236, "output_tokens": 0 }
}
```

**Branch**

```python
a = answers
if a["legible"]["truth"] < 0.8:
    ask_for_new_photo(claim)
elif a["matches"]["truth"] >= 0.9 and a["currency"]["choice"] == claim["currency"]:
    approve(claim)
else:
    reject(claim, reason="receipt does not match the claim")  # and request a corrected receipt
```

## Listing photo verifier

**Problem:** a marketplace wants listing photos to show the actual item in the stated condition. **Build:** compare the listing record with its first photo. The score answer gives an expected condition of 2.15 (between good and like new), with the probabilities to back it.

Request:

```json
{
  "model": "decisionnode-latest",
  "state": {
    "listing": {
      "title": "Oak dining table, seats 6",
      "condition": "like new",
      "finish": "natural oak"
    }
  },
  "images": [
    { "id": "photo_1", "media_type": "image/webp", "data": "<base64>" }
  ],
  "questions": {
    "shows_item": {
      "type": "truth",
      "instructions": "Does photo_1 show the item described in the listing?"
    },
    "condition": {
      "type": "score",
      "instructions": "What condition is the item in, judging by the photo?",
      "criteria": ["damaged", "worn", "good", "like new"]
    },
    "photo_kind": {
      "type": "choice",
      "instructions": "What kind of photo is this?",
      "criteria": {
        "own": "a real photo of this item",
        "stock": "a catalogue or stock image",
        "unclear": "cannot tell"
      }
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "shows_item": { "type": "truth", "truth": 0.88 },
    "condition": {
      "type": "score",
      "score": 2.15,
      "confidence": 0.55,
      "legend": { "0": "damaged", "1": "worn", "2": "good", "3": "like new" },
      "probabilities": { "0": 0.02, "1": 0.11, "2": 0.57, "3": 0.3 }
    },
    "photo_kind": {
      "type": "choice",
      "choice": "own",
      "confidence": 0.73,
      "probabilities": { "own": 0.82, "stock": 0.14, "unclear": 0.04 }
    }
  },
  "usage": { "input_tokens": 1108, "output_tokens": 0 }
}
```

> **Read the distribution, not only the score** The probability that the item is at least "good" is 0.57 + 0.30 = 0.87. That is often a better gate than the expected level itself. See [Score](https://decisionnode.com/docs/concepts/score).

## Lead scoring

**Problem:** sales wants the signups worth a reply today at the top. **Build:** score fit on your own rubric, classify intent, and filter out personal projects, all from the text of the form.

Request:

```json
{
  "model": "decisionnode-flash-latest",
  "state": "Signup form. Company: 40-person logistics startup. Role: head of engineering. Message: We classify about 200k shipping exceptions a day with an LLM and it is too slow and too expensive. Want to test this next week.",
  "questions": {
    "fit": {
      "type": "score",
      "instructions": "How well does this lead fit a high-volume API product?",
      "criteria": ["poor", "possible", "good", "excellent"]
    },
    "intent": {
      "type": "choice",
      "instructions": "What does this person want right now?",
      "criteria": {
        "buying": "ready to buy or start a trial",
        "researching": "comparing options",
        "support": "an existing customer with a problem",
        "other": "none of these"
      }
    },
    "personal": {
      "type": "truth",
      "instructions": "Is this a personal or student project?"
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0-flash",
  "answers": {
    "fit": {
      "type": "score",
      "score": 2.12,
      "confidence": 0.48,
      "legend": {
        "0": "poor",
        "1": "possible",
        "2": "good",
        "3": "excellent"
      },
      "probabilities": { "0": 0.03, "1": 0.14, "2": 0.51, "3": 0.32 }
    },
    "intent": {
      "type": "choice",
      "choice": "buying",
      "confidence": 0.61,
      "probabilities": {
        "buying": 0.71,
        "other": 0.03,
        "researching": 0.22,
        "support": 0.04
      }
    },
    "personal": { "type": "truth", "truth": 0.08 }
  },
  "usage": { "input_tokens": 131, "output_tokens": 0 }
}
```

**Branch**

```typescript
const { fit, intent, personal } = answers;
const priority = personal.truth > 0.5 ? 0 : fit.score * (intent.choice === "buying" ? 2 : 1);
await crm.update(lead.id, { priority, intent: intent.choice });
```

## Statement reader that chases late invoices

**Problem:** finance reads customer statements by hand to decide who gets a reminder. **Build:** two [Number](https://decisionnode.com/docs/concepts/number) questions count the overdue invoices (4, probability 0.84) and read how late the oldest one is (78 days), and a Choice picks the reminder. The reminder goes out on its own.

Request:

```json
{
  "model": "decisionnode-latest",
  "state": "Customer statement\nAccount: Norrvik Supply AB (30-4471)\nStatement date: 2026-10-01\nTerms: net 30, amounts in EUR\n\nInvoice   Issued      Due         Amount    Status\nINV-2041  2026-06-15  2026-07-15  1,240.00  open\nINV-2058  2026-07-03  2026-08-02    410.00  paid 2026-08-01\nINV-2063  2026-07-21  2026-08-20    860.00  open\nINV-2069  2026-07-29  2026-08-28    395.00  paid 2026-09-02\nINV-2077  2026-08-06  2026-09-05  1,120.00  part paid, 300.00 open\nINV-2081  2026-08-13  2026-09-12    640.00  open\nINV-2090  2026-08-31  2026-09-30    780.00  paid 2026-09-29\nINV-2094  2026-09-10  2026-10-10    520.00  open\nINV-2102  2026-09-24  2026-10-24    915.00  open",
  "questions": {
    "overdue": {
      "type": "number",
      "instructions": "How many invoices on this statement are overdue on the statement date?",
      "min": 0,
      "max": 30
    },
    "oldest_days": {
      "type": "number",
      "instructions": "How many days past its due date is the oldest unpaid invoice?",
      "min": 0,
      "max": 180
    },
    "reminder": {
      "type": "choice",
      "instructions": "Which reminder should go out today?",
      "criteria": {
        "none": "nothing is overdue, send nothing",
        "friendly": "a friendly reminder for one recent invoice",
        "firm": "a firm reminder listing every overdue invoice",
        "final": "a final notice before the account is passed to collections"
      }
    }
  }
}
```

Response:

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "overdue": {
      "type": "number",
      "number": 4,
      "expected": 3.99,
      "confidence": 0.84,
      "probabilities": {
        "2": 0.01,
        "3": 0.07,
        "4": 0.84,
        "5": 0.07,
        "6": 0.01
      }
    },
    "oldest_days": {
      "type": "number",
      "number": 78,
      "expected": 78.08,
      "confidence": 0.61,
      "probabilities": {
        "75": 0.01,
        "76": 0.03,
        "77": 0.13,
        "78": 0.61,
        "79": 0.14,
        "80": 0.05,
        "81": 0.02,
        "82": 0.01
      }
    },
    "reminder": {
      "type": "choice",
      "choice": "firm",
      "confidence": 0.68,
      "probabilities": {
        "final": 0.19,
        "firm": 0.76,
        "friendly": 0.04,
        "none": 0.01
      }
    }
  },
  "usage": { "input_tokens": 445, "output_tokens": 0 }
}
```

**Branch**

```python
overdue, oldest, reminder = a["overdue"], a["oldest_days"], a["reminder"]

if overdue["confidence"] >= 0.7 and reminder["confidence"] >= 0.6:
    send_reminder(account, template=reminder["choice"],
                  overdue=overdue["number"], oldest_days=oldest["number"])
else:
    # unsure: the gentlest reminder is the safe path, still sent automatically
    send_reminder(account, template="friendly")
```

## Agent that asks before it acts

**Problem:** an agent with tools can do real damage on one bad call. **Build:** pass each proposed tool call to DecisionNode and run it only when the answer clears your bar. The full recipe is in [Guardrails](https://decisionnode.com/docs/patterns/guardrails).

---

# State

Section: Concepts · URL: 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.

## What to send

Send the input exactly as your system has it. A support message can go as a string; a ticket with its metadata reads better as JSON, because field names tell the model what each value is.

Text:

```json
{
  "state": "Customer: I was charged twice and nobody has replied for 3 days."
}
```

JSON object:

```json
{
  "state": {
    "channel": "email",
    "plan": "team",
    "open_tickets": 2,
    "message": "I was charged twice and nobody has replied for 3 days."
  }
}
```

JSON array:

```json
{
  "state": [
    { "from": "customer", "text": "I was charged twice." },
    { "from": "agent", "text": "Looking into it." },
    { "from": "customer", "text": "Still nothing after 3 days." }
  ]
}
```

`state` is optional. A question can stand alone when its instructions carry everything, for example a Truth check on a sentence you put in the instructions.

## Read once, shared by every question

The model encodes the state and any images once, then answers every question in the request from that single read. Ten questions about one ticket cost the state's tokens once plus each question's own tokens, so ask everything you need in one request rather than one request per question.

> **One input, one request** If you find yourself sending the same state twice with different questions, merge the questions. It is cheaper and every answer comes from the same read. See [Fan-out](https://decisionnode.com/docs/patterns/fan-out).

## Writing a good state

- **Label what matters.** `{ "plan": "team" }` says more than the word team floating in a paragraph.
- **Leave out what does not.** Large blocks of unrelated text make every decision harder. Trim logs, signatures and quoted history that do not bear on the decision.
- **Keep it stable.** Send fields in the same order and format every time. The model is deterministic, so a stable state gives stable answers.
- **Do not put instructions in the state.** Put them in each question's `instructions`, so the state stays pure data and one state serves many questions.

## Size

A request holds up to 64k tokens (65,536), counting the state, the images and every question. `usage.input_tokens` in the response tells you what a request used. See [Limits](https://decisionnode.com/docs/models/limits).

---

# Questions

Section: Concepts · URL: 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.

**Four types.** Every type names its answer: choice (one of your labels), score (a level on your scale), truth (a probability), number (a value on your grid).

Question types

| Type | Goal | What comes back |
| --- | --- | --- |
| [Choice](https://decisionnode.com/docs/concepts/choice) `choice` | Pick one option from the list you give | `choice` (always one of your keys), `probabilities` per option, `confidence` |
| [Score](https://decisionnode.com/docs/concepts/score) `score` | Place the input on your ordered scale or rubric | `score` (expected level, for example 2.31 of 0 to 3), `probabilities` per level, `legend`, `confidence` |
| [Truth](https://decisionnode.com/docs/concepts/truth) `truth` | Is this statement true? | `truth`, one probability from 0.00 to 1.00 that the statement is true |
| [Number](https://decisionnode.com/docs/concepts/number) `number` | How many, or what value? | `number` (a value on your grid), `expected`, `confidence`, `probabilities` per value |

> **What a Truth answer means** 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.

> **What a Number answer means** 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. See [Number](https://decisionnode.com/docs/concepts/number).

## The questions map

`questions` is an object. Its keys are your names for the questions, and the answers come back under the same keys. Use short, stable names your code can read, such as `route` or `refund`. The keys are labels for your code: the model reads the type, the instructions and the criteria.

```json
{
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Where should this go?",
      "criteria": { "billing": "money", "bug": "broken", "account": "login" }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["routine", "today", "urgent", "critical"]
    },
    "refund": {
      "type": "truth",
      "instructions": "Refund this automatically?"
    }
  }
}
```

## Question fields

- `type` ("choice" | "score" | "truth" | "number", required): Fixes the answer's shape: choice, score, truth or number.
- `instructions` (string): What to decide, in plain words. Optional on every type, but almost always worth one sentence, and a number question reads best with one.
- `criteria` (object | string[]): Choice: an object of option keys to what each option means (up to 255), required. Score: an array of levels from lowest to highest (up to 10), required. Truth: optional `{ "true": "...", "false": "..." }` describing what true and false mean. Number: not used.
- `min, max, step` (number): Number only: the grid of values the answer can take. Default 0 to 255, step 1; up to 256 values in the first release. See [Number](https://decisionnode.com/docs/concepts/number#the-grid).

## Writing questions that work

- **Ask one thing.** "Is this urgent and about billing?" is two questions. Split it and you get two calibrated answers.
- **Describe every option.** `"bug": "something is broken"` beats a bare key. The description is what the model compares against.
- **Cover the space.** If an input can fit none of your options, add one for that, such as `"other": "none of these"`. A choice always returns one of your keys.
- **Order scales from low to high.** Score levels are indexed from 0 in the order you send them, and the expected score depends on that order.
- **Phrase a Truth question as a statement that can be true.** "Does the receipt show the same total as the claim?" reads better than "check the receipt".
- **Give a number question the range it can really take.** "How many cars are visible?" on 0 to 50 for a ten-bay row, not the default 0 to 255. A tight grid puts the probability where it belongs.

---

# Choice

Section: Concepts · URL: 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.

(Answer card: what a choice answer looks like; the shape is given in the text.)

## Request

```json
{
  "route": {
    "type": "choice",
    "instructions": "Where should this go?",
    "criteria": { "billing": "money", "bug": "broken", "account": "login" }
  }
}
```

- `type` ("choice", required): The question type.
- `criteria` (object, required): Option key to description, 1 to 255 options (two or more make a real choice). The keys are what comes back.
- `instructions` (string): What to decide.

## Response

```json
{
  "route": {
    "type": "choice",
    "choice": "billing",
    "confidence": 0.81,
    "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
  }
}
```

- `choice` (string): The most likely option. Always one of the keys you sent.
- `probabilities` (object): One entry per option, alphabetical by key. They sum to 1, up to rounding.
- `confidence` (number): How sure the model is, from 0 to 1. See the formula below.

## How confidence is computed

```
confidence = (K · p_max − 1) / (K − 1)
```

- K: the number of options you sent

- p_max: the probability of the chosen option

Confidence is 0 when every option is equally likely and 1 when one option has all the probability. For the route above, K is 3 and p_max is 0.87, so confidence is (3 × 0.87 − 1) / 2 = 0.81. It is computed from the unrounded probabilities. Because it rescales by K, a confidence of 0.8 means the same thing on a 3-way and a 10-way choice.

> **Gate on confidence, not on p_max** A p_max of 0.6 is decisive among ten options and weak between two. Confidence corrects for that. See [Confidence-gated routing](https://decisionnode.com/docs/patterns/confidence-gated-routing).

---

# Score

Section: Concepts · URL: 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.

(Answer card: what a score answer looks like; the shape is given in the text.)

## Request

```json
{
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this?",
    "criteria": ["routine", "today", "urgent", "critical"]
  }
}
```

`criteria` is an array of levels from lowest to highest, up to 10 of them (two or more make a scale). Level indexes start at 0 in the order you send them.

## Response

```json
{
  "urgency": {
    "type": "score",
    "score": 2.31,
    "confidence": 0.47,
    "legend": {
      "0": "routine",
      "1": "today",
      "2": "urgent",
      "3": "critical"
    },
    "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
  }
}
```

- `score` (number): The expected level index: the sum of each index times its probability.
- `probabilities` (object): Level index to probability, in level order.
- `legend` (object): Level index to your level text, exactly as sent.
- `confidence` (number): How tightly the probability sits around the most likely level, from 0 to 1.

## Formulas

```
score = sum(i · p_i)
confidence = 1 − E[|i − m|] / D(K)
D(K) = floor(K · K / 4) / K
```

- i: the level index, from 0

- p_i: the probability of level i

- K: the number of levels

- m: the most likely level, the lowest one on a tie

- E[|i − m|]: the expected distance from m: sum(p_i · |i − m|)

- D(K): the largest that distance can be on K levels

Confidence is 1 when all the probability sits on one level. Probability on a level next to the most likely one costs little, and probability far from it costs a lot, so a scale split between two neighbours still reads as fairly sure. With two levels it equals the choice formula.

**Worked example**

```
score = 0 · 0.01 + 1 · 0.09
      + 2 · 0.48 + 3 · 0.42 = 2.31
m     = 2 (urgent)
E     = 0.01 · 2 + 0.09 · 1
      + 0.48 · 0 + 0.42 · 1 = 0.53
D(4)  = floor(4 · 4 / 4) / 4 = 1
confidence = 1 − 0.53 / 1 = 0.47
```

These are the probabilities from the response above. A middling confidence with a high score is common and useful: the model is sure the ticket is at least urgent, and split between urgent and critical.

## Using a score

- **As a number:** sort or prioritise by `score` directly. It is continuous, so 2.31 ranks above 2.12.
- **As a level:** `round(score)` gives the nearest level; read its name from `legend`.
- **As a tail probability:** add the probabilities of the levels you care about. Here the chance of urgent or worse is 0.48 + 0.42 = 0.90, which is often the gate you actually want.

---

# Truth

Section: Concepts · URL: 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.

(Answer card: what a truth answer looks like; the shape is given in the text.)

## Request

```json
{
  "refund": {
    "type": "truth",
    "instructions": "Refund this automatically?",
    "criteria": {
      "true": "Charged twice for the same order, or charged for an order that failed",
      "false": "Any other billing issue, including requests that need more details first"
    }
  }
}
```

- `type` ("truth", required): The question type.
- `instructions` (string): The statement to test, or a question that is either true or false.
- `criteria` (object): Optional. `criteria.true` says what counts as true and `criteria.false` what counts as false. Use it when the line between them needs drawing; leave it out when the question is plain.

## Response

```json
{
  "refund": { "type": "truth", "truth": 0.94 }
}
```

A Truth answer carries only `type` and `truth`, rounded to two decimals. There is no separate confidence field: the distance from 0.50 already says how sure the model is. 0.94 is confidently true, 0.06 confidently false, and 0.50 means the model cannot tell.

## True or false

Across DecisionNode (the playground, the console and these docs) a Truth answer is shown as its number followed by **true** or **false**: `0.94 true`, `0.03 false`, `0.61 true`. The label is `truth` with a 0.50 threshold applied: 0.50 or more reads true, anything below reads false. It is a reading aid, not a field. The API returns only the number.

- **What true and false mean** is yours to define, in `criteria.true` and `criteria.false` on the request. The model answers against those two descriptions.
- **Where your code acts** is also yours, and it is usually stricter than 0.50. The refund above acts at 0.80, which is why the card at the top of this page marks that point on the gauge.

> **Read the number, not the label** 0.51 and 0.99 both read true. Branch on `truth` against a threshold you chose, so a borderline true never triggers the same action as a certain one.

## Choosing a threshold

Pick the threshold from the cost of each mistake. For refunds, a needless refund costs a little money and a missed one can cost the customer, so refund at 0.80 or more, re-check the unsure middle (0.40 to 0.80) with the full model, and reply without a refund below 0.40.

> **Re-checking only helps after a Flash call** The same request to the same model always returns the same answer. Send the first call to Flash (`decisionnode-flash-latest`), as the code below does, and re-check the middle with `decisionnode-latest`. If the first call already used the full model, take the safe path in the middle instead.

Where acting wrongly is expensive, as with an agent's tool call, raise the bar to 0.95 and take the safe action below it. Either way your code decides on its own, the moment the answer lands.

Python:

```python
REFUND_AT, RECHECK_FROM = 0.8, 0.4

# first call: decide(ticket, model="decisionnode-flash-latest")
p = answers["refund"]["truth"]
if p >= RECHECK_FROM and p < REFUND_AT:   # the unsure middle: ask the full model
    p = recheck(ticket, model="decisionnode-latest")["refund"]["truth"]

if p >= REFUND_AT:
    issue_refund(ticket)
else:
    reply(ticket, template="no_refund")
```

TypeScript:

```typescript
const REFUND_AT = 0.8, RECHECK_FROM = 0.4;

// first call: decide(ticket, { model: "decisionnode-flash-latest" })
let p = answers.refund.truth;
if (p >= RECHECK_FROM && p < REFUND_AT) {
  // the unsure middle: ask the full model
  p = (await recheck(ticket, { model: "decisionnode-latest" })).refund.truth;
}

if (p >= REFUND_AT) await issueRefund(ticket);
else await reply(ticket, { template: "no_refund" });
```

---

# Number

Section: Concepts · URL: 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.

(Answer card: what a number answer looks like; the shape is given in the text.)

A number question asks for one value on a grid you set. Above, a customer statement goes in as text and `overdue` comes back as 4 with probability 0.84, the full distribution over 0 to 30 beside it. It is the fourth type, next to [Choice](https://decisionnode.com/docs/concepts/choice), [Score](https://decisionnode.com/docs/concepts/score) and [Truth](https://decisionnode.com/docs/concepts/truth), and it is read the same way: a typed answer with probabilities you can threshold.

> **Supported grids** The first release serves whole-number grids of up to 256 values; halves, decimals and wider grids follow.

## What it answers

- **Counts:** cars in a drone frame, items on a shelf, pallets in a bay, overdue invoices in a statement, open findings in a report, steps in a plan another model wrote.
- **Values read off the input:** the year a contract was signed, the days until a deadline, the percentage of a page that is tables, a price in a stated range.
- **Ratings and brackets:** a review's rating out of ten (in halves once they follow the first release), an age bracket from a form, a severity from 1 to 5 when the levels are plain numbers.

Use a [Score](https://decisionnode.com/docs/concepts/score) when each level has a meaning in words (routine, urgent, critical). Use a number when the answer is a quantity, and the values in between mean what they say.

## Request

```json
{
  "cars": {
    "type": "number",
    "instructions": "How many cars are visible in the image?",
    "min": 0,
    "max": 50
  }
}
```

- `type` ("number", required): The question type.
- `instructions` (string): What to count or read, in one sentence. The same field as on every type.
- `min` (number): The lowest value the answer can take. Default 0.
- `max` (number): The highest value, at least `min`. Default 255.
- `step` (number): The spacing of the grid, above 0. Default 1: whole numbers, what the first release serves. `0.5` (halves) and `0.1` (one decimal) follow.

A number question uses no `criteria`: the grid is the set of answers. Keep `min` at or below `max`, and use a supported grid.

## Response

```json
{
  "cars": {
    "type": "number",
    "number": 7,
    "expected": 6.97,
    "confidence": 0.77,
    "probabilities": {
      "5": 0.01,
      "6": 0.12,
      "7": 0.77,
      "8": 0.09,
      "9": 0.01
    }
  }
}
```

- `number` (number): The most probable value of the grid. Always a value your grid allows.
- `expected` (number): The probability-weighted mean: a fractional estimate, even on a whole-number grid.
- `confidence` (number): The probability of `number`, from 0 to 1.
- `probabilities` (object): Every grid value with a probability above 0.001, keyed by the value as a string (`"7"`, `"3.5"`). They sum to 1, up to rounding.

```
expected = sum(v · p_v)
confidence = p_number
```

- v: a value of the grid

- p_v: the probability of v

- p_number: the probability of the most probable value

Keys are written the shortest way: `"7"`, never `"7.0"`; `"3.5"`, never `"3.50"`. Parse them as numbers before you sort: in most languages an object keeps `"10"` ahead of `"2.5"`.

## On text

A statement as an accounting system exports it, with two number questions and a [Choice](https://decisionnode.com/docs/concepts/choice) in one request. `overdue` counts the invoices past due on the statement date (4); `oldest_days` reads how late the oldest one is (78, expected 78.08); `reminder` picks what to send. Every answer comes from one read of the statement.

`POST https://api.decisionnode.com/v1/decide`

```
Customer statement
Account: Norrvik Supply AB (30-4471)
Statement date: 2026-10-01
Terms: net 30, amounts in EUR

Invoice   Issued      Due         Amount    Status
INV-2041  2026-06-15  2026-07-15  1,240.00  open
INV-2058  2026-07-03  2026-08-02    410.00  paid 2026-08-01
INV-2063  2026-07-21  2026-08-20    860.00  open
INV-2069  2026-07-29  2026-08-28    395.00  paid 2026-09-02
INV-2077  2026-08-06  2026-09-05  1,120.00  part paid, 300.00 open
INV-2081  2026-08-13  2026-09-12    640.00  open
INV-2090  2026-08-31  2026-09-30    780.00  paid 2026-09-29
INV-2094  2026-09-10  2026-10-10    520.00  open
INV-2102  2026-09-24  2026-10-24    915.00  open
```

The request carries that statement as its `state`, one JSON string. Below it reads as a placeholder so the questions stay in view; the copy button copies the full request, statement included, ready to run.

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "<statement.txt, above>",
    "questions": {
      "overdue": {
        "type": "number",
        "instructions": "How many invoices on this statement are overdue on the statement date?",
        "min": 0,
        "max": 30
      },
      "oldest_days": {
        "type": "number",
        "instructions": "How many days past its due date is the oldest unpaid invoice?",
        "min": 0,
        "max": 180
      },
      "reminder": {
        "type": "choice",
        "instructions": "Which reminder should go out today?",
        "criteria": {
          "none": "nothing is overdue, send nothing",
          "friendly": "a friendly reminder for one recent invoice",
          "firm": "a firm reminder listing every overdue invoice",
          "final": "a final notice before the account is passed to collections"
        }
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": "<statement.txt, above>",
      "questions": {
        "overdue": {
          "type": "number",
          "instructions": "How many invoices on this statement are overdue on the statement date?",
          "min": 0,
          "max": 30
        },
        "oldest_days": {
          "type": "number",
          "instructions": "How many days past its due date is the oldest unpaid invoice?",
          "min": 0,
          "max": 180
        },
        "reminder": {
          "type": "choice",
          "instructions": "Which reminder should go out today?",
          "criteria": {
            "none": "nothing is overdue, send nothing",
            "friendly": "a friendly reminder for one recent invoice",
            "firm": "a firm reminder listing every overdue invoice",
            "final": "a final notice before the account is passed to collections"
          }
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "<statement.txt, above>",
    "questions": {
      "overdue": {
        "type": "number",
        "instructions": "How many invoices on this statement are overdue on the statement date?",
        "min": 0,
        "max": 30
      },
      "oldest_days": {
        "type": "number",
        "instructions": "How many days past its due date is the oldest unpaid invoice?",
        "min": 0,
        "max": 180
      },
      "reminder": {
        "type": "choice",
        "instructions": "Which reminder should go out today?",
        "criteria": {
          "none": "nothing is overdue, send nothing",
          "friendly": "a friendly reminder for one recent invoice",
          "firm": "a firm reminder listing every overdue invoice",
          "final": "a final notice before the account is passed to collections"
        }
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();
```

**200 OK**

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "overdue": {
      "type": "number",
      "number": 4,
      "expected": 3.99,
      "confidence": 0.84,
      "probabilities": {
        "2": 0.01,
        "3": 0.07,
        "4": 0.84,
        "5": 0.07,
        "6": 0.01
      }
    },
    "oldest_days": {
      "type": "number",
      "number": 78,
      "expected": 78.08,
      "confidence": 0.61,
      "probabilities": {
        "75": 0.01,
        "76": 0.03,
        "77": 0.13,
        "78": 0.61,
        "79": 0.14,
        "80": 0.05,
        "81": 0.02,
        "82": 0.01
      }
    },
    "reminder": {
      "type": "choice",
      "choice": "firm",
      "confidence": 0.68,
      "probabilities": {
        "final": 0.19,
        "firm": 0.76,
        "friendly": 0.04,
        "none": 0.01
      }
    }
  },
  "usage": { "input_tokens": 445, "output_tokens": 0 }
}
```

## On an image

(Example card: a drone frame, the cars counted on it, and the typed number answer.)

The frame goes in `images`, the question asks for a count on a 0 to 50 grid, and the answer is a number your code can store, compare or act on. DecisionNode reads the image itself, in the same pass as the state and the question: there is no caption step in between.

`POST https://api.decisionnode.com/v1/decide`

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "Drone frame over row B4 of the north car park, camera pointing straight down.",
    "images": [
      { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "cars": {
        "type": "number",
        "instructions": "How many cars are visible in the image?",
        "min": 0,
        "max": 50
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": "Drone frame over row B4 of the north car park, camera pointing straight down.",
      "images": [
        { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
      ],
      "questions": {
        "cars": {
          "type": "number",
          "instructions": "How many cars are visible in the image?",
          "min": 0,
          "max": 50
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]

cars = answers["cars"]
if cars["confidence"] >= 0.7:
    occupancy.log(row="B4", cars=cars["number"])   # sure: act on 7
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "Drone frame over row B4 of the north car park, camera pointing straight down.",
    "images": [
      { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "cars": {
        "type": "number",
        "instructions": "How many cars are visible in the image?",
        "min": 0,
        "max": 50
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();

const { cars } = answers;
if (cars.confidence >= 0.7) {
  await occupancy.log({ row: "B4", cars: cars.number }); // sure: act on 7
}
```

> **Give small objects the pixels they need** Count where every object is clearly visible. Many small objects need a sharper image, within the image limits on [Limits](https://decisionnode.com/docs/models/limits) (up to 10 MB each). Crop to the area that matters rather than sending the whole scene.

## The grid

`min`, `max` and `step` set every value the answer can take. Without them the grid is 0 to 255 in whole numbers. A grid of up to 256 values is answered as one question. A finer or wider grid is composed inside the same call (the whole part and the decimals, for example), and you still get one answer.

Grids and what they ask for

| Grid | Request | Values | First release |
| --- | --- | --- | --- |
| Cars in a frame | `"min": 0, "max": 50` | 51 | Yes |
| Year a contract was signed | `"min": 1990, "max": 2026` | 37 | Yes |
| Default range | no `min`, `max` or `step` | 256 | Yes |
| Rating in halves | `"min": 0, "max": 5, "step": 0.5` | 11 | Follows |
| Percentage, one decimal | `"min": 0, "max": 100, "step": 0.1` | 1,001 | Follows |

> **What the first release serves** The first release serves whole-number grids of up to 256 values; halves, decimals and wider grids follow. A grid this release does not serve (a step below 1, or more than 256 values) is refused with an `api_usage_error` that names the grid, and nothing is charged. See [Errors](https://decisionnode.com/docs/api/errors#over-a-limit-400).

## Reading the answer

- **Act on `number`** when `confidence` clears the bar you set for this question. The frame above, 7 at 0.77, is a count your code can log, bill or route on.
- **Use `expected`** where a fractional estimate is better than a whole one: averages across many frames, forecasts, sorting.
- **Read `probabilities`** for the shape. A split answer, "probably 7, maybe 8", looks like `{"6": 0.21, "7": 0.62, "8": 0.14}`: `number` is 7 at 0.62, and adding its neighbours gives 0.97, the chance the true value is within one.

"Probably 7, maybe 8" never waits on anyone. Below your bar, your code escalates on its own: it re-checks with DecisionNode-1.0 when the first call went to DecisionNode-1.0 Flash, and if the answer is still split it takes the safe end of what is likely, such as planning for 8 cars rather than 7.

Python:

```python
# decide(request) posts the request to /v1/decide and returns its answers
ACT_AT = 0.7   # per question, in config

def count_cars(request):
    cars = decide({**request, "model": "decisionnode-flash-latest"})["cars"]
    if cars["confidence"] < ACT_AT:     # probably 7, maybe 8: ask the full model
        cars = decide({**request, "model": "decisionnode-latest"})["cars"]
    if cars["confidence"] >= ACT_AT:
        return cars["number"]           # sure: act on it

    # still split: take the high end of the likely values, automatically
    likely = [float(v) for v, p in cars["probabilities"].items() if p >= 0.1]
    return int(max(likely))             # a whole-number grid: an int, like the sure path
```

TypeScript:

```typescript
// your wrapper: posts the request to /v1/decide and returns its answers
import { decide, type DecideRequest } from "./decisionnode";

const ACT_AT = 0.7; // per question, in config

export async function countCars(request: DecideRequest) {
  let { cars } = await decide({ ...request, model: "decisionnode-flash-latest" });
  if (cars.confidence < ACT_AT) {
    // probably 7, maybe 8: ask the full model
    ({ cars } = await decide({ ...request, model: "decisionnode-latest" }));
  }
  if (cars.confidence >= ACT_AT) return cars.number; // sure: act on it

  // still split: take the high end of the likely values, automatically
  const likely = Object.entries(cars.probabilities)
    .filter(([, p]) => p >= 0.1)
    .map(([v]) => Number(v));
  return Math.max(...likely);
}
```

## Beyond counting

- **Retail and logistics:** items on a shelf, pallets in a bay, vehicles in a yard, from one camera frame.
- **Documents:** overdue invoices in a statement, open findings in an audit report, mentions of a product in a thread.
- **Agriculture and inspection:** fruit on a branch, defects on a surface, animals in a pen.
- **Checks on other models:** how many steps a generated plan has, how many sources an answer cites.
- **Values, not counts:** the year a document was issued, a percentage, a price in a stated range, and once finer grids follow, a rating in halves.

## Billing

A number question costs what a [choice](https://decisionnode.com/docs/concepts/choice) with as many options costs: its grid counts like one option per value. A 0 to 50 count is billed like a choice of 51 options. Images are priced as on every call, and [batch jobs](https://decisionnode.com/docs/pricing#batch-jobs) take number questions at half the price, like every other type. Output stays free. See [Pricing and billing](https://decisionnode.com/docs/pricing).

---

# Images

Section: Concepts · URL: 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.

(Example card: a receipt photo sent as an image, with its request and typed answers.)

One photo of a receipt and the expense claim it should back up, in one request. `matches` is a Truth question that compares three fields at once; `currency` is a Choice read straight off the print. Both are answered from a single read of the image.

## Sending an image

Add an `images` array next to the state. Each image has an `id` you choose, a `media_type` and the bytes as base64 in `data`, without a `data:` prefix. Refer to images by id in your instructions when there is more than one.

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": {
      "claim": { "amount": 48.2, "currency": "EUR", "date": "2026-09-28" }
    },
    "images": [
      { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "matches": {
        "type": "truth",
        "instructions": "Does the receipt show the same total, currency and date as the claim?",
        "criteria": {
          "true": "Total, currency and date on the receipt all match the claim",
          "false": "Any of them differs, or the receipt does not show it"
        }
      },
      "currency": {
        "type": "choice",
        "instructions": "Which currency is the receipt in?",
        "criteria": {
          "EUR": "euro",
          "GBP": "pound sterling",
          "USD": "US dollar"
        }
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": {
        "claim": { "amount": 48.2, "currency": "EUR", "date": "2026-09-28" }
      },
      "images": [
        { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
      ],
      "questions": {
        "matches": {
          "type": "truth",
          "instructions": "Does the receipt show the same total, currency and date as the claim?",
          "criteria": {
            "true": "Total, currency and date on the receipt all match the claim",
            "false": "Any of them differs, or the receipt does not show it"
          }
        },
        "currency": {
          "type": "choice",
          "instructions": "Which currency is the receipt in?",
          "criteria": {
            "EUR": "euro",
            "GBP": "pound sterling",
            "USD": "US dollar"
          }
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]

if answers["matches"]["truth"] >= 0.9 and answers["currency"]["choice"] == "EUR":
    approve(claim)          # paid out, no one looks at it
else:
    return_to_sender(claim, reason="receipt does not match")
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": {
      "claim": { "amount": 48.2, "currency": "EUR", "date": "2026-09-28" }
    },
    "images": [
      { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "matches": {
        "type": "truth",
        "instructions": "Does the receipt show the same total, currency and date as the claim?",
        "criteria": {
          "true": "Total, currency and date on the receipt all match the claim",
          "false": "Any of them differs, or the receipt does not show it"
        }
      },
      "currency": {
        "type": "choice",
        "instructions": "Which currency is the receipt in?",
        "criteria": {
          "EUR": "euro",
          "GBP": "pound sterling",
          "USD": "US dollar"
        }
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();

if (answers.matches.truth >= 0.9 && answers.currency.choice === "EUR") {
  await approve(claim); // paid out, no one looks at it
} else {
  await returnToSender(claim, { reason: "receipt does not match" });
}
```

**Image object**
- `id` (string, required): Your name for the image, for example `receipt` or `photo_1`.
- `media_type` (string, required): `image/jpeg`, `image/png` or `image/webp`.
- `data` (string, required): The image bytes, base64 encoded, with no `data:` prefix.

## Encoding a file

Read the file's bytes, base64 encode them and put the text in `data`, with the `media_type` that matches the file. Each image may be up to 10 MB before encoding; the other limits are on [Limits](https://decisionnode.com/docs/models/limits).

Python:

```python
import base64, pathlib

raw = pathlib.Path("receipt.jpg").read_bytes()
data = base64.b64encode(raw).decode()
image = {"id": "receipt", "media_type": "image/jpeg", "data": data}
```

TypeScript:

```typescript
import { readFile } from "node:fs/promises";

const data = (await readFile("receipt.jpg")).toString("base64");
const image = { id: "receipt", media_type: "image/jpeg", data };
```

## What the model reads

- Printed and handwritten text, including totals, dates and reference numbers.
- Objects and their condition, as in a listing photo.
- Layout: which number is the total, which line is the date, whether a stamp or signature is present.
- Several images against each other, such as a photo and the document it should match.
- How many: cars in a drone frame, items on a shelf, with a [Number](https://decisionnode.com/docs/concepts/number) question.

> **Images count as input tokens** Images are encoded once with the state and count toward `usage.input_tokens` and the 64k context. Up to 4 images per request. Downscale large photos before sending; a long side around 1,500 px keeps text legible.

---

# Confidence

Section: Concepts · URL: 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.

## What calibrated means

Take every Truth answer the model gave near 0.9. If about nine in ten of those statements are actually true, the probabilities are calibrated. That is what makes a threshold meaningful: at 0.9 you accept about one wrong answer in ten among the ones that pass, and you can reason about that before you ship.

## Where confidence lives in each type

Confidence by question type

| Type | Field to gate on | Range and meaning |
| --- | --- | --- |
| Choice | `confidence` | 0 when all options are equally likely, 1 when one option has all the probability |
| Score | `confidence`, or a sum of `probabilities` | How tightly the levels sit around the most likely one; tail sums answer "at least level n" |
| Truth | `truth` | The probability that the statement is true; distance from 0.50 is how sure it is |
| Number | `confidence`, or a sum of `probabilities` | The probability of `number`; add its neighbours for the chance the true value is within one |

### Choice confidence

```
confidence = (K · p_max − 1) / (K − 1)
```

- K: the number of options

- p_max: the probability of the chosen option

### Score confidence

```
confidence = 1 − E[|i − m|] / D(K)
D(K) = floor(K · K / 4) / K
```

- K: the number of levels

- m: the most likely level, the lowest one on a tie

- E[|i − m|]: the expected distance from m: sum(p_i · |i − m|)

Both are computed from the unrounded probabilities, then rounded to 2 decimals. A score's confidence is 1 when all the probability sits on one level, and probability next to the most likely level costs little. With two levels the two formulas agree. The [Score](https://decisionnode.com/docs/concepts/score#formulas) page works one through.

## Choosing a threshold

1. Start at 0.7 for choice and number confidence and 0.8 for Truth gates.
2. Run a few hundred real inputs whose outcome you already know, such as resolved tickets or settled disputes.
3. For each threshold, measure two numbers: how many inputs pass, and how many of those are wrong.
4. Pick the threshold where the error rate is one your product can live with. Above it your code acts instantly; below it, it takes the safe action or re-checks with the full model.
5. Re-check after you change the questions or move to a new model version.

> **Thresholds belong to a question and a model** Changing the instructions, the options or the model version changes the distribution. Keep thresholds in config next to the question they belong to, and pin the model version in production.

---

# Determinism

Section: Concepts · URL: 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.

## Same request, same answer

The model reads the request in one pass and returns the answer directly; nothing is sampled, so there is no temperature or seed to set. Send a request twice and you get the same probabilities to the last digit.

## Pin the version

`decisionnode-latest` moves to new versions as we release them. The `model` field in every response says which version answered. Where answers must not change, send the pinned id instead.

Model ids

| Send | Answers from | Use when |
| --- | --- | --- |
| `decisionnode-latest` | the newest version, today `decisionnode-1.0` | you want improvements as they ship |
| `decisionnode-1.0` | exactly that version | answers must stay identical: tests, audits, tuned thresholds |

## What changes an answer

- Any change to the state, images, instructions or criteria, even whitespace.
- The order of options in `criteria` for a score (it defines the levels), and the option keys and descriptions for a choice.
- A different model version.

## What you can build on it

- **Snapshot tests:** post a fixed request in CI and assert the answer, the way you would test a pure function.
- **Caching:** hash the request body and cache the response. A hit is exactly what the API would have returned.
- **Audit trails:** store the request and the `x-request-id`; replaying the request on the pinned version reproduces the decision.

---

# DecisionNode-1.0

Section: Models · URL: 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 at a glance

- `model` id: `decisionnode-latest` (today `decisionnode-1.0`)
- Answers: Choice, Score and Truth, calibrated per question type; Number
- Input: Text, JSON and images in one request
- Context: 64k tokens per request (65,536)
- Price: $0.042 per 1M input tokens, output free
- Runs on: Our own inference stack and our own GPUs

## When to use it

Use the full model when the decision is subtle: long threads, many options, images with small print, rubrics where the levels are close together. It is the default in these docs and in the playground.

## How it answers

It reads the state, the images and every question in one pass and returns every answer directly. It generates no text, which is why output is free and why the answer always has the shape its type defines.

## Calling it

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": "Customer: I was charged twice and nobody has replied for 3 days.",
      "questions": {
        "route": {
          "type": "choice",
          "instructions": "Where should this go?",
          "criteria": {
            "billing": "money",
            "bug": "broken",
            "account": "login"
          }
        },
        "urgency": {
          "type": "score",
          "instructions": "How urgent is this?",
          "criteria": ["routine", "today", "urgent", "critical"]
        },
        "refund": {
          "type": "truth",
          "instructions": "Refund this automatically?"
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();
```

The same request costs $0.0000026 on DecisionNode-1.0. Compare it with [DecisionNode-1.0 Flash](https://decisionnode.com/docs/models/flash) on your own inputs in the [playground](https://decisionnode.com/playground): the model picker switches between them without changing anything else.

---

# DecisionNode-1.0 Flash

Section: Models · URL: 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).

DecisionNode-1.0 Flash at a glance

- `model` id: `decisionnode-flash-latest` (today `decisionnode-1.0-flash`)
- Speed: About 5 ms for a short request, server side (measured October 2026)
- Input: The same fields as the full model: state, images, questions
- Context: 64k tokens per request
- Price: $0.021 per 1M input tokens (provisional), output free

## When to use it

- High volume: moderation of every comment, triage of every event, scoring of every row.
- Inside a latency budget: a check on the hot path of a request, or a gate in front of every agent step.
- Clear decisions: short inputs and well separated options, where the full model's extra capacity is not needed.

> **Try both on your data** Run a sample of real inputs through both models. Where Flash agrees with the full model above your confidence threshold, use Flash; route the rest to the full model. This is a two-line change, because only `model` differs.

## Calling it

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-flash-latest",
      "state": "Customer: I was charged twice and nobody has replied for 3 days.",
      "questions": {
        "route": {
          "type": "choice",
          "instructions": "Where should this go?",
          "criteria": {
            "billing": "money",
            "bug": "broken",
            "account": "login"
          }
        },
        "urgency": {
          "type": "score",
          "instructions": "How urgent is this?",
          "criteria": ["routine", "today", "urgent", "critical"]
        },
        "refund": {
          "type": "truth",
          "instructions": "Refund this automatically?"
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-flash-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();
```

Only `model` changes. At $0.021 per million, the 62-token request above costs $0.0000013, and a million of them about $1.30.

---

# Limits

Section: Models · URL: https://decisionnode.com/docs/models/limits

Context size, image limits, question limits and default throughput per workspace. These apply to both models.

Request limits

| Limit | Value | Notes | Over the limit |
| --- | --- | --- | --- |
| Context per request | 64k tokens (65,536) | State, images and every question together | `400` `max_tokens_exceeded` |
| Images per request | Up to 4 | JPEG, PNG or WebP, base64 in `data` | `400` `api_usage_error` |
| Image size | Up to 10 MB each | Measured on the image bytes; base64 text is about a third longer | `400` `api_usage_error` |
| Options per choice | 1 to 255 | Two or more recommended | `400` Too many choices |
| Levels per score | 1 to 10 | Lowest first; two or more recommended | `400` Too many score levels |
| Values per number question | Up to 256 | Whole-number grids in the first release; halves, decimals and wider grids follow | `400` `api_usage_error` |
| Response | One buffered JSON body | On `/v1/decide` every answer arrives together; [sessions](https://decisionnode.com/docs/api/sessions) (announced, not yet served) stream one reply per frame |  |

A request over a limit is refused before any model work and costs nothing. The state is never cut to make it fit, and the body names the limit you crossed. Bodies and fixes are on [Errors](https://decisionnode.com/docs/api/errors#over-a-limit-400).

## Sessions (announced, not yet served)

Sessions stream decisions over one open connection, for control loops that decide more than 10 times a second. Their limits apply on top of the request limits above.

Session limits

| Limit | Value | Notes |
| --- | --- | --- |
| Frame | At most 4,096 tokens, or one image | Text, a JSON value or an image |
| Window | 8 recent frames by default | Set with `window` when the session opens |
| Lifetime | 300 seconds by default, at most 3,600 | Set with `ttl_seconds` |
| Sessions per key | Published at [`/v1/models`](https://decisionnode.com/docs/api/models) | One session per socket |

## Throughput

New workspaces start at 40 requests per second and 100,000 input tokens per second (provisional defaults). Your current limits are in the [console](https://decisionnode.com/console/keys). Over the limit, the API answers 429 with a `Retry-After` header. See [Rate limits](https://decisionnode.com/docs/api/rate-limits).

> **Need more?** Dedicated capacity runs on GPUs reserved for you, with limits set to your traffic. Ask through the console and we will size it with you.

---

# Confidence-gated routing

Section: Patterns · URL: 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.

## The shape of it

1. Ask your questions in one request to DecisionNode-1.0 Flash, the fastest tier.
2. If confidence clears the threshold, act on the answer at once.
3. If it does not, send the same request to DecisionNode-1.0 and act on that answer when it clears the bar.
4. If neither clears it, take the safe action your product defines. Log every decision with the model that made it.

Python:

```python
THRESHOLDS = {"route": 0.7}   # per question, in config

def handle(ticket, request):
    for model in ("decisionnode-flash-latest", "decisionnode-latest"):
        route = decide({**request, "model": model})["route"]
        if route["confidence"] >= THRESHOLDS["route"]:
            queues[route["choice"]].put(ticket)
            return log(ticket, decided_by=model, answer=route)
    queues["general"].put(ticket)           # the safe default, still automatic
    log(ticket, decided_by="safe_default", answer=route)
```

TypeScript:

```typescript
const THRESHOLDS = { route: 0.7 }; // per question, in config
const CASCADE = ["decisionnode-flash-latest", "decisionnode-latest"] as const;

export async function handle(ticket: Ticket, request: DecideRequest) {
  let route: ChoiceAnswer | undefined;
  for (const model of CASCADE) {
    ({ route } = await decide({ ...request, model }));
    if (route.confidence >= THRESHOLDS.route) {
      await queues[route.choice].put(ticket);
      return log(ticket, { decidedBy: model, answer: route });
    }
  }
  await queues.general.put(ticket); // the safe default, still automatic
  await log(ticket, { decidedBy: "safe_default", answer: route });
}
```

## Tuning the threshold

Your outcomes are the labels: reopened tickets, refunds charged back, comments restored on appeal. After a week, compute for a few thresholds how much traffic Flash settles on its own, how much the full model settles, and how often either was wrong. Raise the threshold if the error rate is too high; lower it if the full model agrees with Flash on nearly every re-check.

Reading a threshold sweep

| Signal | What it means | Move |
| --- | --- | --- |
| The full model agrees with almost every re-check | The threshold is stricter than it needs to be | Lower it |
| Automatic answers are wrong too often | The threshold is too loose | Raise it |
| Many items sit just below the line | The question may be ambiguous | Rewrite the options or split the question |

> **Two thresholds for Truth** For a `truth` gate use a band: act above 0.8, take the opposite action below 0.2, and re-check the middle with the full model. The band's width is how many requests take a second call.

> **Decisions about people are the exception** Gate tickets, payments, posts and tool calls fully automatically. A consequential decision about a person in hiring, credit, housing, insurance, education, benefits, law enforcement or health needs a qualified person to review it before it takes effect. See [Responsible use](https://decisionnode.com/docs/responsible-use).

---

# Fan-out

Section: Patterns · URL: 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.

## Many questions, one request

The state is read once and shared by every question, so put every question about an input into one request. Ten questions cost the state's tokens once, not ten times, and all ten answers come from the same read of the input.

```json
{
  "model": "decisionnode-flash-latest",
  "state": "Refund my order 4471 or I will dispute the charge with my bank.",
  "questions": {
    "refund_request": {
      "type": "truth",
      "instructions": "Is the customer asking for a refund?"
    },
    "chargeback_threat": {
      "type": "truth",
      "instructions": "Does the customer threaten a chargeback?"
    },
    "order_id_present": {
      "type": "truth",
      "instructions": "Does the message include an order number?"
    },
    "sentiment": {
      "type": "score",
      "criteria": ["calm", "annoyed", "angry", "furious"]
    },
    "language": {
      "type": "choice",
      "criteria": {
        "en": "English",
        "de": "German",
        "es": "Spanish",
        "other": "another language"
      }
    }
  }
}
```

## Many inputs, in parallel

Each request is independent, so a backlog parallelises cleanly. Bound the concurrency so you stay under your limits (by default 40 requests per second, provisional) and retry 429s after `Retry-After`.

Python:

```python
import asyncio, os, httpx

LIMIT = asyncio.Semaphore(16)

async def decide(client, state):
    async with LIMIT:
        r = await client.post("https://api.decisionnode.com/v1/decide", json={
            "model": "decisionnode-flash-latest",
            "state": state,
            "questions": QUESTIONS,
        })
        r.raise_for_status()
        return r.json()["answers"]

async def run(states):
    headers = {"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"}
    async with httpx.AsyncClient(headers=headers, timeout=10) as client:
        return await asyncio.gather(*(decide(client, s) for s in states))
```

TypeScript:

```typescript
async function runAll<T>(items: T[], worker: (item: T) => Promise<unknown>, concurrency = 16) {
  const results: unknown[] = new Array(items.length);
  let next = 0;
  await Promise.all(
    Array.from({ length: concurrency }, async () => {
      while (next < items.length) {
        const i = next++;
        results[i] = await worker(items[i]);
      }
    }),
  );
  return results;
}

const answers = await runAll(tickets, (t) => decide({ state: t.body, questions: QUESTIONS }));
```

> **Ask everything in one request** The state is read once and shared by every question in the request, so ten questions on the same document cost little more than one. Group questions about the same input into one call instead of sending the document again.

---

# Guardrails

Section: Patterns · URL: 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.

## Where the check goes

Put the check between the agent deciding to call a tool and the tool running. The state is the proposed call plus the context that matters; the questions are your policy, written as Truth and Choice questions.

**Gate request**

```json
{
  "model": "decisionnode-flash-latest",
  "state": {
    "user_request": "Clean up the old staging data",
    "proposed_call": {
      "tool": "run_sql",
      "args": {
        "database": "production",
        "sql": "DELETE FROM orders WHERE created_at < '2026-01-01'"
      }
    }
  },
  "questions": {
    "safe": {
      "type": "truth",
      "instructions": "Is it safe to run this call right now?",
      "criteria": {
        "true": "read-only, reversible, or clearly what the user asked for",
        "false": "destructive, irreversible, or outside what the user asked for"
      }
    },
    "in_scope": {
      "type": "truth",
      "instructions": "Does the call do what the user asked, and nothing more?"
    },
    "risk": {
      "type": "choice",
      "instructions": "What is the main risk of this call?",
      "criteria": {
        "none": "no meaningful risk",
        "data_loss": "deletes or overwrites data",
        "money": "moves money or changes billing",
        "privacy": "exposes personal data",
        "other": "another kind of risk"
      }
    }
  }
}
```

**Gate**

```typescript
const BAR = { safe: 0.95, inScope: 0.9 };

export async function guardedCall(call: ToolCall, context: Context) {
  let answers;
  try {
    answers = await decide(gateRequest(call, context));
  } catch {
    return block(call, { reason: "guardrail unavailable" }); // fail closed: the agent re-plans
  }

  const { safe, in_scope, risk } = answers;
  if (safe.truth >= BAR.safe && in_scope.truth >= BAR.inScope) {
    return runTool(call);
  }
  return block(call, { reason: risk.choice, safe: safe.truth, inScope: in_scope.truth });
}
```

> **Fail closed** If the gate cannot answer (a timeout, a 529), do not run the tool. Block the call and hand the reason back to the agent so it re-plans. A guardrail that fails open is not a guardrail.

## Why it works as a gate

- **Fast enough for every step:** Flash answers short requests in milliseconds, so the check fits in front of every tool call.
- **Deterministic:** the same proposed call gets the same verdict, so you can test your policy with fixed cases in CI.
- **Calibrated:** a bar of 0.95 means what it says. Pin `decisionnode-1.0` or `decisionnode-1.0-flash` once the bar is tuned.

---

# Control loops (announced, not yet served)

Section: Patterns · URL: 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.

## When to use a session

Which call for which rate

| You decide | Use | Why |
| --- | --- | --- |
| Now and then: a ticket, a payment, a tool call | [`POST /v1/decide`](https://decisionnode.com/docs/api/decide) | Each decision stands alone; one request, one answer |
| Many inputs at once | [Fan-out](https://decisionnode.com/docs/patterns/fan-out) or a batch job | Parallel requests within your rate limits, or half price when it can wait |
| More than 10 times a second, on one evolving input | [A session](https://decisionnode.com/docs/api/sessions) (announced, not yet served) | The context is sent once and stays loaded; each frame carries only what changed |

> **The rule of thumb** More than 10 decisions a second about the same thing: open a session. Fewer, or about different things: call `/v1/decide`.

## A decision layer, never the controller

A vehicle runs in layers. The inner loop keeps it stable, many times a second, on its own controller. Above it sits a layer that decides what to do: continue or abort, which mode, which manoeuvre next. That is the layer a session serves. Its answers feed your controller, which stays in charge of the vehicle.

Where DecisionNode sits in a control stack

| Layer | Decides | Runs on |
| --- | --- | --- |
| Mission and planning | The route, the task, the next job | Your planner, with `/v1/decide` calls when it needs a judgment |
| Decision layer | Which mode now, continue or abort, the next action | A DecisionNode session (announced, not yet served) |
| Inner control loop | Attitude, speed, motors, brakes | Your flight or motion controller, untouched |

> **Never the sole means of control** DecisionNode returns decision outputs. It is not designed, tested or certified as the only control of any vehicle, aircraft or machine whose failure could cause harm. Keep your controller, its own limits and an independent fallback in place, and follow the aviation and product-safety rules that apply to you. See the [Terms](https://decisionnode.com/legal/terms).

## The loop

(Diagram: the fixed part of a session is sent once, frames stream in, the newest answer feeds the controller.)

1. Open a session once, with the mission brief as `state` and the questions every frame should answer.
2. On every tick, send only what changed as a frame: telemetry, a sensor reading, a camera frame.
3. Hand each reply to your controller as a request, not a command: it applies the mode when the answer clears your threshold and the controller's own limits allow it.
4. When no fresh reply has arrived by your deadline, the controller keeps its current mode or runs its own failsafe. Your code decides that on its own, every time.
5. End the session when the mission ends.

[Sessions](https://decisionnode.com/docs/api/sessions#clients) has the full client in Python and TypeScript: one task streams frames, one reads replies and hands them on.

## Designing frames

- **Put the constant part in the session.** The brief, the rules and the geofence go in `state` once; frames carry readings.
- **Keep frames small.** A frame holds at most 4,096 tokens or one image. Name the fields (`battery`, `wind_mps`) so the model knows what each value is.
- **Choose the window for the decision.** A mode change that depends on a trend needs a few recent frames; a reflex check on the current frame needs one. Send `"reset": true` when the situation changes completely, such as after landing.
- **Ask only what this tick needs.** List `questions` on a frame to answer some of them; each frame is billed for the questions it asks.

## What to build

- **Drones and vehicles, civilian:** mission supervision for survey, inspection and delivery flights; return, hold and land decisions; mode selection.
- **Simulators and games:** the next manoeuvre or action from a stream of state.
- **Industrial monitoring:** machine state to action, alert or hold, from sensor frames.
- **Long-running agents:** stream tool results and get a typed next step, without resending the whole context each time.

> **Civilian use only, outside a Defence Contract Addendum** Without a signed [Defence Contract Addendum](https://decisionnode.com/legal/defence-addendum), sessions serve civilian control loops only: the [Acceptable Use Policy](https://decisionnode.com/legal/acceptable-use) forbids weapons, harmful payloads and targeting. Under an addendum, its own rules apply, and what its Section 4 forbids stays forbidden in every case.

---

# POST /v1/decide

Section: API reference · URL: 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.

**Request**

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": [
          "routine",
          "today",
          "urgent",
          "critical"
        ]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }'
```

Python:

```python
import os
import requests

key = os.environ["DECISIONNODE_API_KEY"]

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {key}"},
    json={
      "model": "decisionnode-latest",
      "state": "Customer: I was charged twice and nobody has replied for 3 days.",
      "questions": {
        "route": {
          "type": "choice",
          "instructions": "Where should this go?",
          "criteria": {
            "billing": "money",
            "bug": "broken",
            "account": "login"
          }
        },
        "urgency": {
          "type": "score",
          "instructions": "How urgent is this?",
          "criteria": [
            "routine",
            "today",
            "urgent",
            "critical"
          ]
        },
        "refund": {
          "type": "truth",
          "instructions": "Refund this automatically?"
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const url = "https://api.decisionnode.com/v1/decide";
const key = process.env.DECISIONNODE_API_KEY;

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": [
          "routine",
          "today",
          "urgent",
          "critical"
        ]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }),
});
if (!response.ok) {
  throw new Error(`DecisionNode ${response.status}`);
}
const { answers } = await response.json();
```

**200 OK**

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": {
        "account": 0.05,
        "billing": 0.87,
        "bug": 0.08
      }
    },
    "urgency": {
      "type": "score",
      "score": 2.31,
      "confidence": 0.47,
      "legend": {
        "0": "routine",
        "1": "today",
        "2": "urgent",
        "3": "critical"
      },
      "probabilities": {
        "0": 0.01,
        "1": 0.09,
        "2": 0.48,
        "3": 0.42
      }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": {
    "input_tokens": 62,
    "output_tokens": 0
  }
}
```

`POST https://api.decisionnode.com/v1/decide`

curl:

```bash
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }'
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.decisionnode.com/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json={
      "model": "decisionnode-latest",
      "state": "Customer: I was charged twice and nobody has replied for 3 days.",
      "questions": {
        "route": {
          "type": "choice",
          "instructions": "Where should this go?",
          "criteria": {
            "billing": "money",
            "bug": "broken",
            "account": "login"
          }
        },
        "urgency": {
          "type": "score",
          "instructions": "How urgent is this?",
          "criteria": ["routine", "today", "urgent", "critical"]
        },
        "refund": {
          "type": "truth",
          "instructions": "Refund this automatically?"
        }
      }
    },
    timeout=10,
)
response.raise_for_status()
answers = response.json()["answers"]
```

TypeScript:

```typescript
const response = await fetch("https://api.decisionnode.com/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "decisionnode-latest",
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Where should this go?",
        "criteria": {
          "billing": "money",
          "bug": "broken",
          "account": "login"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["routine", "today", "urgent", "critical"]
      },
      "refund": {
        "type": "truth",
        "instructions": "Refund this automatically?"
      }
    }
  }),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { answers } = await response.json();
```

## Headers

- `Authorization` (string, required): `Bearer dn_live_...`. Keep keys on your server and read them from an environment variable such as `DECISIONNODE_API_KEY`.
- `Content-Type` (string, required): `application/json`.

## Request body

- `model` (string, required): `decisionnode-latest` or `decisionnode-flash-latest`, or a pinned version such as `decisionnode-1.0`.
- `state` (string | object | array): The input to decide about: text, a JSON object or a JSON array. Read once and shared by every question.
- `images` (array): Up to 4 images, read together with the state.
  - `id` (string, required): Your name for the image.
  - `media_type` (string, required): `image/jpeg`, `image/png` or `image/webp`.
  - `data` (string, required): Base64 bytes, no `data:` prefix.
- `questions` (object, required): Your question keys mapped to question objects. Answers come back under the same keys.
  - `type` ("choice" | "score" | "truth" | "number", required): Fixes the answer's shape: choice, score, truth or number.
  - `instructions` (string): What to decide, in one sentence.
  - `criteria` (object | string[]): Choice: option key to description, required, up to 255. Score: levels lowest first, required, up to 10. Truth: optional `{"true": "...", "false": "..."}`, what true and what false mean. Number: not used, the grid is the set of answers.
  - `min` (number): Number only: the lowest value. Default 0.
  - `max` (number): Number only: the highest value, at least `min`. Default 255.
  - `step` (number): Number only: the grid spacing, above 0. Default 1. Up to 256 values in the first release; see [Number](https://decisionnode.com/docs/concepts/number#the-grid).

## Response body

```json
{
  "model": "decisionnode-1.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
    },
    "urgency": {
      "type": "score",
      "score": 2.31,
      "confidence": 0.47,
      "legend": {
        "0": "routine",
        "1": "today",
        "2": "urgent",
        "3": "critical"
      },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": { "input_tokens": 62, "output_tokens": 0 }
}
```

- `model` (string): The pinned version that answered, for example `decisionnode-1.0`.
- `answers` (object): One answer per question key.
  - `choice answer` (object): `type`, `choice` (one of your keys), `confidence`, `probabilities` (alphabetical by key).
  - `score answer` (object): `type`, `score` (expected level index), `confidence`, `legend`, `probabilities` (in level order).
  - `truth answer` (object): `type` (`"truth"`) and `truth`, the probability that the statement is true, from 0.00 to 1.00.
  - `number answer` (object): `type`, `number` (the most probable grid value), `expected` (the probability-weighted mean), `confidence` (the probability of `number`), `probabilities` (every value above 0.001, keyed by the value as a string).
- `usage` (object): `input_tokens` billed for this request, and `output_tokens`, which is always 0.

> **Rules of the shape** Numbers are rounded to 2 decimals. A choice's confidence is `(K × p_max − 1) / (K − 1)` for K options. A score is the expected level index, and its confidence is `1 − E[|level − mode|] / D(K)`, where mode is the most likely level and `D(K) = floor(K × K / 4) / K`. Both confidences are computed before rounding. A truth answer carries only `type` and `truth`. A number answer's confidence is the probability of `number`, and its `expected` is the sum of each value times its probability. See [Confidence](https://decisionnode.com/docs/concepts/confidence).

> **Compatibility: the noul alias** A question sent with `"type": "noul"` is accepted as the same type as `truth` and answered in its own name, `{ "type": "noul", "noul": 0.94 }`, so code written for a Jev-shaped API keeps working unchanged. New code should send `truth`. See [Coming from a Jev-shaped API](https://decisionnode.com/docs/coming-from-jev).

## Response headers

Response headers

| Header | Example | Meaning |
| --- | --- | --- |
| `x-request-id` | `req_01J9Z6K4M2` | Quote it when you contact us; store it with the decision |
| `x-decisionnode-latency-ms` | `6` | Time spent on our side, in milliseconds |
| `x-decisionnode-model` | `decisionnode-1.0` | The model version that answered, as in `model` |
| `Retry-After` | `2` | Seconds to wait before retrying, sent with every 429 and 529 |

## Errors

Error statuses

| Status | Meaning |
| --- | --- |
| `400` | Outside a limit (options, levels, 64k tokens, a number grid the first release does not serve), an unknown model or a bad image; the message names it |
| `401` | Missing or invalid API key |
| `402` | Out of credit; add credit in the console, then retry. Not billed. See [Errors](https://decisionnode.com/docs/api/errors#out-of-credit) |
| `403` | Refused by the safety check (`safety_refusal`); rolling out in shadow mode, see [Errors](https://decisionnode.com/docs/api/errors#safety-refusal) |
| `422` | The body failed validation; `detail` lists each invalid field |
| `429` | Rate limited; wait for `Retry-After` |
| `529` | Overloaded; wait for `Retry-After`, then retry |

Bodies, retry rules and code are in [Errors](https://decisionnode.com/docs/api/errors).

> **Deciding many times a second?** `/v1/decide` answers one request with one response. For more than 10 decisions a second about the same thing, a [session](https://decisionnode.com/docs/api/sessions) (announced, not yet served) keeps your context loaded and streams one typed reply per frame.

---

# Sessions (announced, not yet served)

Section: API reference · URL: 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.

> **Coming: sessions are announced, not yet served** This page documents the shapes sessions will use. What it does not state yet (the full open response, close codes, error bodies) is published at release, together with measured per-frame latency for both models.

A call to [/v1/decide](https://decisionnode.com/docs/api/decide) sends everything every time: the instructions, the context and the questions. A session sends that fixed part once. The model keeps your context loaded for the life of the session, so each frame you stream costs only its own tokens, and each reply carries the same typed, calibrated answers as a normal call. [Control loops](https://decisionnode.com/docs/patterns/control-loops) covers when to use one.

(Diagram: the fixed part of a session is sent once, frames stream in, the newest answer feeds the controller.)

## Open a session

`POST https://api.decisionnode.com/v1/sessions`

**Request body**

```json
{
  "model": "decisionnode-latest",
  "instructions": "You are the mission supervisor of a survey drone.",
  "state": {
    "mission": "Survey the north field in parallel lines, 40 m altitude",
    "geofence": "Stay inside the field boundary and below 120 m",
    "rules": "Return home when battery is under 30% at the far end of a line"
  },
  "questions": {
    "mode": {
      "type": "choice",
      "instructions": "Which flight mode now?",
      "criteria": {
        "continue": "keep flying the survey pattern",
        "hold": "hover in place until conditions change",
        "return": "fly back to the home point",
        "land": "land at the nearest safe spot now"
      }
    },
    "abort": {
      "type": "truth",
      "instructions": "Should the mission be aborted now?"
    }
  },
  "window": 8
}
```

curl:

```bash
# the body above, saved as session.json
curl https://api.decisionnode.com/v1/sessions \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @session.json
```

Python:

```python
import json, os, requests

SESSION = json.load(open("session.json"))   # the body above

response = requests.post(
    "https://api.decisionnode.com/v1/sessions",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    json=SESSION,
    timeout=10,
)
response.raise_for_status()
session_id = response.json()["session_id"]
```

TypeScript:

```typescript
import { readFileSync } from "node:fs";

const SESSION = JSON.parse(readFileSync("session.json", "utf8")); // the body above

const response = await fetch("https://api.decisionnode.com/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(SESSION),
});
if (!response.ok) throw new Error(`DecisionNode ${response.status}`);
const { session_id } = await response.json();
```

- `model` (string, required): Either model, or a pinned version, as on `/v1/decide`.
- `instructions` (string): Who the model is deciding as, for every frame of the session.
- `state` (string | object | array): The static context: a mission brief, a rulebook, a map legend. Read once, within the 64k request limit.
- `questions` (object, required): The questions every frame is answered on, in the same shape as on `/v1/decide`: choice, score, truth or number.
- `window` (number): How many recent frames stay in context. Default 8.
- `ttl_seconds` (number): How long the session lives. Default 300, at most 3,600.

**What comes back**
- `session_id` (string): The session's id. Use it to open the stream and to end the session.

The response also carries the stream URL (`wss://api.decisionnode.com/v1/sessions/{id}/stream`) and the limits that apply to each frame. Their exact field names are published at release.

## Stream frames

`WS wss://api.decisionnode.com/v1/sessions/{id}/stream`

Connect from your server with your key in the `Authorization` header (`Bearer dn_live_...`), as on every call. Each message you send is one frame; each message you receive is the reply to one frame.

Frame:

```json
{
  "seq": 17,
  "frame": {
    "battery": 0.31,
    "wind_mps": 11.4,
    "distance_home_m": 820,
    "obstacle": "none"
  }
}
```

Only some questions:

```json
{
  "seq": 18,
  "frame": {
    "battery": 0.31,
    "wind_mps": 11.4,
    "distance_home_m": 820,
    "obstacle": "none"
  },
  "questions": ["abort"]
}
```

Reset the window:

```json
{
  "seq": 19,
  "frame": {
    "battery": 0.31,
    "wind_mps": 11.4,
    "distance_home_m": 820,
    "obstacle": "none"
  },
  "reset": true
}
```

**Frame**
- `seq` (number, required): Your sequence number for the frame. The reply carries it back.
- `frame` (string | object | image, required): What changed: text, a JSON value or one image, at most 4,096 tokens. How an image frame is encoded is published at release.
- `questions` (string[]): The question names to answer this time. All of them when left out.
- `reset` (boolean): `true` drops the recent frames from context before this one is answered.

## Replies

```json
{
  "seq": 17,
  "answers": {
    "mode": {
      "type": "choice",
      "choice": "return",
      "confidence": 0.79,
      "probabilities": {
        "continue": 0.09,
        "hold": 0.05,
        "land": 0.02,
        "return": 0.84
      }
    },
    "abort": { "type": "truth", "truth": 0.07 }
  }
}
```

**Reply**
- `seq` (number): The sequence number of the frame this answers.
- `answers` (object): One answer per question asked, exactly as `/v1/decide` shapes it, with the same calibration.
- `latency_ms` (number): Time spent on our side for this frame, in milliseconds.
- `safety` (object): The safety check's probabilities for this frame. Every frame passes the same check as every call.

## How a session behaves

- **Rolling window.** Each frame is answered on the fixed part plus the last `window` frames (8 by default), so the model sees what just happened. Older frames leave the context. Send `"reset": true` to start the window over.
- **Latest wins.** If frames arrive faster than they are answered, the newest frame is answered and the skipped sequence numbers are reported to you. A client that falls behind gets the newest answer, never a backlog. If you need every frame answered, send the next one after its reply.
- **Lifetime.** A session ends at `ttl_seconds` (300 by default, at most 3,600), when the socket closes, or when you end it. If it ends early, the socket closes with a code your client can read: open a new session with the same body and carry on.
- **One session per socket.** Run several sessions on several sockets, within the sessions your key may hold.

## End a session

`DELETE https://api.decisionnode.com/v1/sessions/{id}`

```bash
curl -X DELETE https://api.decisionnode.com/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"
```

Ending a session frees its context at once. Closing the socket ends it too.

## Limits

Session limits

| Limit | Value |
| --- | --- |
| Frame | At most 4,096 tokens, or one image |
| Fixed part | Within the 64k request limit, as on [Limits](https://decisionnode.com/docs/models/limits) |
| Window | 8 recent frames by default |
| Lifetime | 300 seconds by default, at most 3,600 |
| Sessions per key | Published at [`/v1/models`](https://decisionnode.com/docs/api/models) |

## Billing

```
session = opening tokens × price
        + sum(frame tokens × price)
```

- opening tokens: the instructions, the state and the questions, billed once when the session opens

- frame tokens: each frame's own tokens plus the questions it asks

- price: the live price per input token of the session's model, today $0.042 per million on DecisionNode-1.0

Output stays free. The context is never billed again per frame, which is what makes a long session cheap. See [Pricing and billing](https://decisionnode.com/docs/pricing#sessions).

## Clients

Open the session over HTTPS, then stream. One task sends frames at your sensor's rate; another reads replies and hands each typed answer to your own controller, which keeps flying, driving or running while it waits.

Python:

```python
import asyncio, json, os
import websockets  # pip install websockets

KEY = os.environ["DECISIONNODE_API_KEY"]
MODE_AT, ABORT_AT = 0.7, 0.9   # your thresholds, in config

async def supervise(session_id, telemetry, autopilot):
    url = f"wss://api.decisionnode.com/v1/sessions/{session_id}/stream"
    headers = {"Authorization": f"Bearer {KEY}"}
    async with websockets.connect(url, additional_headers=headers) as ws:

        async def send_frames():
            seq = 0
            async for reading in telemetry:          # your sensor loop, at its own rate
                seq += 1
                await ws.send(json.dumps({"seq": seq, "frame": reading}))

        async def read_replies():
            async for message in ws:
                reply = json.loads(message)
                # under latest wins a reply may also list the seqs it skipped
                # (the field is published at release); the newest answer is what counts
                mode = reply["answers"]["mode"]
                abort = reply["answers"]["abort"]
                # the autopilot flies; the session only proposes a mode
                if abort["truth"] >= ABORT_AT:
                    autopilot.request_mode("return", seq=reply["seq"])
                elif mode["confidence"] >= MODE_AT:
                    autopilot.request_mode(mode["choice"], seq=reply["seq"])
                # below both bars the autopilot keeps its current mode

        await asyncio.gather(send_frames(), read_replies())
```

TypeScript:

```typescript
import WebSocket from "ws"; // npm install ws

const KEY = process.env.DECISIONNODE_API_KEY!;
const MODE_AT = 0.7, ABORT_AT = 0.9; // your thresholds, in config

type Choice = { type: "choice"; choice: string; confidence: number; probabilities: Record<string, number> };
type Truth = { type: "truth"; truth: number };
type Reply = { seq: number; answers: { mode: Choice; abort: Truth } };

// your side of the loop: the sensor feed and the controller that flies
interface Telemetry { onReading(listener: (frame: Record<string, unknown>) => void): void }
interface Autopilot { requestMode(mode: string, seq: number): void }

export function supervise(sessionId: string, telemetry: Telemetry, autopilot: Autopilot) {
  const ws = new WebSocket(`wss://api.decisionnode.com/v1/sessions/${sessionId}/stream`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });

  let seq = 0;
  ws.on("open", () => {
    // your sensor loop, at its own rate
    telemetry.onReading((frame) => {
      if (ws.readyState !== WebSocket.OPEN) return; // closed: your controller keeps its mode
      ws.send(JSON.stringify({ seq: ++seq, frame }));
    });
  });

  ws.on("message", (data) => {
    // under latest wins a reply may also list the seqs it skipped (the field
    // is published at release); the newest answer is what counts
    const reply = JSON.parse(data.toString()) as Reply;
    const { mode, abort } = reply.answers;
    // the autopilot flies; the session only proposes a mode
    if (abort.truth >= ABORT_AT) autopilot.requestMode("return", reply.seq);
    else if (mode.confidence >= MODE_AT) autopilot.requestMode(mode.choice, reply.seq);
    // below both bars the autopilot keeps its current mode
  });

  return () => ws.close();
}
```

## Published at release

- Measured per-frame latency for both models.
- The full open response, beyond `session_id` and the stream URL.
- How an image frame is encoded, and how skipped frames are listed in a reply.
- Close codes and error bodies.
- The sessions each key may hold, at `/v1/models`.

---

# GET /v1/models

Section: API reference · URL: 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.

**Request**

curl:

```bash
curl https://api.decisionnode.com/v1/models \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"
```

Python:

```python
import os, requests

r = requests.get(
    "https://api.decisionnode.com/v1/models",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    timeout=10,
)
for m in r.json()["models"]:
    print(m["name"], "->", m["version"])
```

TypeScript:

```typescript
const r = await fetch("https://api.decisionnode.com/v1/models", {
  headers: { Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}` },
});
const { models } = await r.json();
const pinned = Object.fromEntries(models.map((m) => [m.name, m.version]));
```

**200 OK**

```json
{
  "models": [
    {
      "name": "decisionnode-latest",
      "description": "Our most accurate decision model",
      "release_date": "2026-10-01",
      "version": "decisionnode-1.0",
      "context_tokens": 65536,
      "max_images": 4,
      "max_choices": 255,
      "max_levels": 10
    },
    {
      "name": "decisionnode-flash-latest",
      "description": "The fastest and cheapest tier",
      "release_date": "2026-10-01",
      "version": "decisionnode-1.0-flash",
      "context_tokens": 65536,
      "max_images": 4,
      "max_choices": 255,
      "max_levels": 10
    }
  ]
}
```

`GET https://api.decisionnode.com/v1/models`

curl:

```bash
curl https://api.decisionnode.com/v1/models \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"
```

Python:

```python
import os, requests

r = requests.get(
    "https://api.decisionnode.com/v1/models",
    headers={"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"},
    timeout=10,
)
for m in r.json()["models"]:
    print(m["name"], "->", m["version"])
```

TypeScript:

```typescript
const r = await fetch("https://api.decisionnode.com/v1/models", {
  headers: { Authorization: `Bearer ${process.env.DECISIONNODE_API_KEY}` },
});
const { models } = await r.json();
const pinned = Object.fromEntries(models.map((m) => [m.name, m.version]));
```

## Headers

- `Authorization` (string, required): `Bearer dn_live_...`. The request has no body and no parameters; the list depends only on your key.

Call it once at startup to check a key and to log which pinned version `decisionnode-latest` answers from. It sends no tokens, so it costs nothing.

## Response body

```json
{
  "models": [
    {
      "name": "decisionnode-latest",
      "description": "Our most accurate decision model",
      "release_date": "2026-10-01",
      "version": "decisionnode-1.0",
      "context_tokens": 65536,
      "max_images": 4,
      "max_choices": 255,
      "max_levels": 10
    },
    {
      "name": "decisionnode-flash-latest",
      "description": "The fastest and cheapest tier",
      "release_date": "2026-10-01",
      "version": "decisionnode-1.0-flash",
      "context_tokens": 65536,
      "max_images": 4,
      "max_choices": 255,
      "max_levels": 10
    }
  ]
}
```

- `models` (array): One entry per name your key may send.
  - `name` (string): What you send as `model`.
  - `description` (string): What the model is for.
  - `release_date` (string): When this name started answering, as `YYYY-MM-DD`.
  - `version` (string): The pinned version the name answers from today. Send it as `model` to pin.
  - `context_tokens` (number): Maximum tokens per request, 65,536.
  - `max_images` (number): Images per request.
  - `max_choices` (number): Options per choice question.
  - `max_levels` (number): Levels per score question.

Prices per million input tokens are on [Pricing and billing](https://decisionnode.com/docs/pricing). Code that reads only `name`, `description` and `release_date` keeps working: the other fields are extra.

When [sessions](https://decisionnode.com/docs/api/sessions) (announced, not yet served) ship, this list also publishes how many sessions your key may hold open.

---

# Errors

Section: API reference · URL: 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.

Statuses

| Status | Meaning | Retry? | What to do |
| --- | --- | --- | --- |
| `400` Bad request | Valid JSON, but outside a limit (too many options or levels, over 64k tokens), an unknown model or a bad image | No | Fix the request; the message names the limit |
| `401` Unauthorized | Missing or invalid API key | No | Check the `Authorization` header and that the key is not revoked |
| `402` Out of credit | The workspace's prepaid balance is zero. Not billed | After top-up | Add credit in the console, or turn on auto reload, then retry |
| `403` Safety refusal | Refused by the safety check: the request asks for a use the Acceptable Use Policy forbids. Rolling out in shadow mode | No | Change what the request asks; see [Responsible use](https://decisionnode.com/docs/responsible-use) |
| `422` Unprocessable | The body failed validation | No | Fix the fields listed in `detail` |
| `429` Too many requests | Over your rate limit | Yes | Wait `Retry-After` seconds, then retry |
| `529` Overloaded | No capacity right now | Yes | Wait `Retry-After` seconds, then retry with backoff and jitter |

## Error bodies

`detail` is a list for 422. For 401, 402, 403, 429 and 529 it is an object with `error_type` and `message`. A 400 can take any of three shapes: an object with `error_type` and `message`, an object with only `error_type` (`max_tokens_exceeded`), or a plain string for a question's limits. Check its type before you branch on it.

A 422 lists every invalid field at once: `loc` is the path into your body (with the question's key and type), and `input` echoes what you sent there, so your own error message can point at the exact field.

400:

```json
{
  "detail": {
    "error_type": "api_usage_error",
    "message": "Unknown model: decisionode-latest"
  }
}
```

401:

```json
{
  "detail": {
    "error_type": "authentication_error",
    "message": "Cannot authenticate with the server. Please check your API key and try again."
  }
}
```

402:

```json
{
  "detail": {
    "error_type": "insufficient_credit",
    "message": "Your prepaid balance is empty. Add credit in the console to continue."
  }
}
```

403:

```json
{
  "detail": {
    "error_type": "safety_refusal",
    "message": "This request was refused by the safety check. See the Acceptable Use Policy."
  }
}
```

422:

```json
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "questions", "route", "choice", "criteria"],
      "msg": "Field required",
      "input": { "type": "choice", "instructions": "Where should this go?" }
    }
  ]
}
```

429:

```json
{
  "detail": {
    "error_type": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds."
  }
}
```

529:

```json
{
  "detail": {
    "error_type": "overloaded",
    "message": "Temporarily overloaded. Retry with backoff."
  }
}
```

## Over a limit: 400

A request that parses but asks for more than a model allows is refused before any model work, and nothing is charged. The body says which limit you crossed, so log it as it is. The limits themselves are on [Limits](https://decisionnode.com/docs/models/limits).

What a request over a limit gets back

| Case | Body |
| --- | --- |
| More than 255 options | `{"detail": "Too many choices. Must have at most 255 choices."}` |
| More than 10 score levels | `{"detail": "Too many score levels. Must have at most 10 levels."}` |
| A number grid the first release does not serve (over 256 values, or a step below 1) | The `api_usage_error` shape, with a message that names the grid. Do not depend on the exact message wording |
| Over 64k tokens | `{"detail": {"error_type": "max_tokens_exceeded"}}` |
| Unknown model | `{"detail": {"error_type": "api_usage_error", "message": "Unknown model: <name>"}}` |
| Bad image | The `api_usage_error` shape, with a message that names the problem: undecodable, an unsupported type or over the size limit |

A number question needs `min` at or below `max`, and uses no `criteria`: its grid is the set of answers. Keep the grid within the supported limits.

> **Never resend a 400 unchanged** The same request gets the same 400. Trim the state, split the options across two questions or fix the model name, then send it again.

## Out of credit: 402

Requests draw down a prepaid balance. When it reaches zero, every request returns HTTP 402 with `{"detail": {"error_type": "insufficient_credit", "message": "..."}}` until credit is added, so a runaway job cannot spend money you did not put in. A refused request is not billed and runs no model work.

Do not retry a 402 in a loop: it keeps failing until the balance has credit again. Turn on auto reload under [Billing](https://decisionnode.com/console/billing) so the balance tops itself up before it runs out, and alert on any 402 your service still sees. [Pricing and billing](https://decisionnode.com/docs/pricing#prepaid-balance) has the details.

## Refused by the safety check: 403

Every request passes an automatic safety check before the model answers. It refuses a narrow set of uses that the [Acceptable Use Policy](https://decisionnode.com/legal/acceptable-use#safety-check) forbids: choosing whom to harm by a protected trait (race, religion, sex, disability and the others the policy lists), the lethal targeting of people, and help to self-harm. Detecting a risk is never refused: asking whether a message shows a risk of self-harm, or whether a post is a threat, is answered as usual.

A refused request returns HTTP 403 with `{"detail": {"error_type": "safety_refusal", "message": "..."}}` instead of answers. Nothing about it is worth retrying: the same request is refused again. A refused request is not charged (pending confirmation).

> **Rolling out in shadow mode** The check runs in shadow mode first: it records and flags requests it would refuse, and still answers them. Handle the 403 now, so your code is ready when enforcement starts. [Responsible use](https://decisionnode.com/docs/responsible-use) covers the rest of the rules.

## Retrying

Python:

```python
import random, time, requests

def decide(body, key, attempts=5):
    for attempt in range(attempts):
        r = requests.post(
            "https://api.decisionnode.com/v1/decide",
            json=body,
            headers={"Authorization": f"Bearer {key}"},
            timeout=10,
        )
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 1)))
            continue
        if r.status_code == 529:
            # Retry-After is the server's estimate: wait at least that long
            backoff = min(8, 0.25 * 2 ** attempt)
            wait = max(float(r.headers.get("Retry-After", 0)), backoff)
            time.sleep(wait + random.random() / 4)
            continue
        if not r.ok:
            # 400, 401, 402, 403, 422: retrying will not help.
            # (402 clears only once credit is added.)
            # detail is a list, an object or a string: log it whole.
            detail = r.json().get("detail")
            raise RuntimeError(f"{r.status_code}: {detail!r}")
        return r.json()
    raise RuntimeError("DecisionNode: out of retries")
```

TypeScript:

```typescript
const sleep = (ms: number) =>
  new Promise((done) => setTimeout(done, ms));

export async function decide(body: unknown, key: string) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const r = await fetch("https://api.decisionnode.com/v1/decide", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${key}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    if (r.status === 429) {
      const wait = Number(r.headers.get("Retry-After") ?? 1);
      await sleep(wait * 1000);
      continue;
    }
    if (r.status === 529) {
      // Retry-After is the server's estimate: wait at least that long
      const backoff = Math.min(8000, 250 * 2 ** attempt);
      const after = Number(r.headers.get("Retry-After") ?? 0) * 1000;
      await sleep(Math.max(after, backoff) + Math.random() * 250);
      continue;
    }
    if (!r.ok) {
      // 400, 401, 402, 403, 422: retrying will not help.
      // (402 clears only once credit is added.)
      // detail is a list, an object or a string: log it whole.
      const { detail } = await r.json();
      throw new Error(`${r.status}: ${JSON.stringify(detail)}`);
    }
    return r.json();
  }
  throw new Error("DecisionNode: out of retries");
}
```

> **Log the request id** Every response, errors included, carries `x-request-id`. Log it with the status; it is the fastest way for us to find your request.

---

# Rate limits

Section: API reference · URL: 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.

Default limits for a new workspace (provisional)

| Limit | Default | Counted as |
| --- | --- | --- |
| Requests | 40 per second | Every call to `/v1/decide` |
| Input tokens | 100,000 per second | `usage.input_tokens` across all requests |

Both limits are shared by every key in a workspace and by both models. Your current values are on the **Rate limits** tab of [API keys](https://decisionnode.com/console/keys) in the console.

## When you hit a limit

The API answers `429` with a `Retry-After` header in seconds. Wait that long and retry the same request; nothing was charged for the refused one. Retrying sooner only earns another 429.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 2
x-request-id: req_01J9Z6Q8T4
content-type: application/json

{"detail": {"error_type": "rate_limited", "message": "Too many requests. Retry after 2 seconds."}}
```

## Staying under them

- Bound concurrency in batch jobs (see [Fan-out](https://decisionnode.com/docs/patterns/fan-out)) instead of firing everything at once.
- Ask all questions about an input in one request: one request instead of many, and the state counted once.
- Trim states. Tokens per second is usually the limit a backlog hits first.
- Need a higher ceiling or reserved GPUs? Dedicated capacity is set to your traffic; ask through the console.

---

# Pricing and billing

Section: Pricing and billing · URL: 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.

Prices per 1M input tokens

| Model | Model id | Input / 1M | Batch / 1M | Output |
| --- | --- | --- | --- | --- |
| DecisionNode-1.0 | `decisionnode-latest` | $0.042 | $0.021 | Free |
| DecisionNode-1.0 Flash | `decisionnode-flash-latest` | $0.021 (provisional) | $0.0105 (provisional) | Free |
| Dedicated | Reserved capacity on our own GPUs, custom limits: [talk to us](mailto:hello@bynn.com?subject=DecisionNode%20Dedicated) |  |  |  |

## How a request is billed

```
cost = usage.input_tokens
     × price per token
```

- usage.input_tokens: the state, images and every question, as returned in the response

- price per token: the model's price per million, divided by 1,000,000

`usage.output_tokens` is always 0. There are no seats, no minimums and no charge per question: the price depends only on what you send. Requests refused with 400, 401, 402, 422, 429 or 529 are not billed, so you pay only for requests that return answers. A request refused by the safety check (403) is not charged either (pending confirmation).

## Batch jobs

Work that can wait runs as a batch job at half the price per input token, on either model. Output stays free, and a batch answer has the same shape as a real-time one. Batch jobs take every question type, number questions included.

- Batch results come with a multi-hour delay. There is no set time at which a batch runs or finishes.
- Poll the batch job for its results. Nothing is pushed to you.
- Use batches for backfills, nightly scoring and re-checks of past decisions. Anything your software is waiting on belongs in a real-time request.

## Number questions

A [number question](https://decisionnode.com/docs/concepts/number) costs what a choice with the same number of options costs: each value of its grid counts like one option. A count on 0 to 50 is billed like a choice of 51 options, and the default grid of 0 to 255 like one of 256. A tight grid costs less. Images are priced as on every call.

## Sessions (announced, not yet served)

A [session](https://decisionnode.com/docs/api/sessions) bills its context once, when it opens: the instructions, the state and the questions, at the live price per input token. After that, each frame is billed for its own tokens and the questions it asks, at the same live price. The context is never billed again per frame, and output stays free.

```
session = opening tokens × price
        + sum(frame tokens × price)
```

- opening tokens: the instructions, the state and the questions, once

- frame tokens: each frame's own tokens plus the questions it asks

## Worked examples

Each workload asks three questions per request. **Tokens** is `usage.input_tokens` for one request, as the response reports it.

Monthly cost at these volumes

| Workload | Tokens | Requests a month | DecisionNode-1.0 | DecisionNode-1.0 Flash |
| --- | --- | --- | --- | --- |
| Support tickets | 62 | 1,000,000 | $2.60 | $1.30 |
| Comment moderation | 94 | 30,000,000 | $118.44 | $59.22 |
| Receipt photo checks | 1,236 | 200,000 | $10.38 | $5.19 |

## Prepaid balance

- Add credit in the console under [Billing](https://decisionnode.com/console/billing). Requests draw it down token by token.
- Turn on auto reload to top up when the balance drops below an amount you choose.
- Every top-up gets an invoice in the console.
- When the balance reaches zero, requests return [`402` Out of credit](https://decisionnode.com/docs/api/errors#out-of-credit) until you add credit, so a runaway job cannot spend money you did not put in. A refused request is not billed.

## Watching spend

The console's [Usage](https://decisionnode.com/console/usage) page charts spend, tokens and requests by model and by day. In code, read `usage.input_tokens` from each response; it is exactly what was billed.

> **Cut cost without cutting quality** Ask every question about an input in one request, trim states to what the decision needs, and route the clear cases to Flash. Each of these lowers tokens, not accuracy.

---

# Responsible use

Section: Policies · URL: 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.

> **The binding text is the policy** This page explains the [Acceptable Use Policy](https://decisionnode.com/legal/acceptable-use) and the [Terms of Service](https://decisionnode.com/legal/terms) for developers. Where the two differ, the legal pages apply.

## Automatic by default

Routing a ticket, gating an agent's tool call, checking an invoice against its order, moderating a post: set a threshold once, act on every answer above it, and take the safe path below it. Nothing has to wait for a person. The examples in these docs and in the [playground](https://decisionnode.com/playground) are all of this kind.

## Decisions about people

A few areas are different. When DecisionNode helps make a consequential decision about a person in one of the categories below, a qualified person must review each decision before it takes effect. The answer can rank, flag and prepare the case; a person with the competence and the authority to change the outcome signs it off.

Categories that need a qualified person's review

| Category | For example |
| --- | --- |
| Hiring | Screening, ranking or rejecting candidates, promotion and dismissal |
| Credit | Approving, pricing or limiting a loan or a credit line |
| Housing | Accepting or refusing a tenant, setting a deposit |
| Insurance | Accepting a policy holder, pricing a premium, settling a claim |
| Education | Admissions, grading that affects progression, discipline |
| Benefits | Granting, reducing or stopping public or private benefits |
| Law enforcement | Anything that leads to a stop, a search, a charge or a sentence |
| Health | Diagnosis, treatment, triage and access to care |

- **Never on a protected trait.** Do not ask DecisionNode to treat a person less favourably because of race, religion, sex, disability or another characteristic the policy lists. An attribute the decision genuinely depends on, such as income for a loan, is allowed where the law allows it.
- **No inferring sensitive traits** such as health, religion or sexual orientation without the person's explicit consent or a legal basis.
- **Follow the law of your use case.** Anti-discrimination, consumer protection, data protection and AI law (including the EU AI Act) apply to what you build; meeting them is your responsibility.

> **What review means in code** Hold the outcome until a qualified reviewer has signed it off, and apply it only then. Keep the request, the answer and the reviewer's decision together, so each decision can be explained later. See section 3 of the [Acceptable Use Policy](https://decisionnode.com/legal/acceptable-use#decisions-about-people).

## The safety check

Every request passes an automatic safety check. It refuses a narrow set of uses: choosing whom to harm by a protected trait, the lethal targeting of people, and help to self-harm. It never refuses detection: asking whether a message shows a risk of self-harm, whether a post is a threat or whether a payment is fraud is answered as usual, and we encourage it.

A refused request returns HTTP 403 with `{"detail": {"error_type": "safety_refusal", "message": "..."}}` and no answers. The check is rolling out in shadow mode: today it flags requests without refusing them. Handle the 403 now; [Errors](https://decisionnode.com/docs/api/errors#safety-refusal) has the details.

## Military use

Military use is not allowed under the standard terms. It is available only under a signed [Defence Contract Addendum](https://decisionnode.com/legal/defence-addendum), which defence and security bodies of the member states of the North Atlantic Treaty Organization, the member states of the European Union, Australia, Japan, New Zealand and the Republic of Korea (and their contractors) may sign. Even under the addendum some uses stay forbidden in every case, including targeting people by a protected trait or targeting civilians, any weapon of mass destruction, and any decision to use force without a responsible person's authorisation.

## Report misuse

If you see DecisionNode used in a way these rules forbid, write to [abuse@bynn.com](mailto:abuse@bynn.com). Security issues go to [security@bynn.com](mailto:security@bynn.com).

---

# Coming from a Jev-shaped API

Section: Migrate · URL: 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.

> **Independent, not affiliated** DecisionNode is built by Bynn Intelligence, Inc. and is not affiliated with, sponsored by, or endorsed by TypeSafe AI. TypeSafe, Jev and their marks belong to their respective owner and are named here only to identify the API being compared.

**Information last reviewed:** 4 October 2026. **Scope:** the DecisionNode API (`decisionnode-latest`, `decisionnode-flash-latest`) and the TypeSafe AI HTTP API for Jev as described on its public documentation pages listed under Sources. Prices are list prices per million input tokens in USD.

## What to change

The body fields `model`, `state` and `questions` and the response fields `model`, `answers` and `usage` have the same names and roles, so in most integrations three values change: the URL, the key and the model id.

Before:

```typescript
const URL = "https://api.typesafe.ai/v1/systemone";
const KEY = readSecret("TYPESAFE_API_KEY");
const MODEL = "jev-latest";
```

After:

```typescript
const URL = "https://api.decisionnode.com/v1/decide";
const KEY = readSecret("DECISIONNODE_API_KEY");
const MODEL = "decisionnode-latest"; // or "decisionnode-flash-latest"
```

## Side by side

API comparison, as publicly documented on 4 October 2026

|  | DecisionNode | Jev (TypeSafe AI, as documented) |
| --- | --- | --- |
| Endpoint | `POST /v1/decide` on `api.decisionnode.com` | `POST /v1/systemone` on `api.typesafe.ai` |
| Authentication | `Authorization` header, `Bearer <key>` | `Authorization` header, `Bearer <API_KEY>` |
| Request fields | `model` and `questions` required; `state` and `images` optional | Documented as requiring `state`, `model` and `questions` |
| Response fields | `model`, `answers`, `usage` | `model`, `answers`, `usage` |
| Error statuses | 401, 422, 429, 529, plus 400 for a request over a limit, 402 when the prepaid balance is empty and 403 for a safety refusal; every body under the same `detail` key | Documented: 401, 422, 429, 529 |
| Question types | `choice`, `score`, `truth` and `number`; `noul` is accepted as an alias of `truth` and answered under its own name | Documented as three types: `choice`, `score` and `noul` |
| Number answers on a grid | `number` questions: a value on a grid you set, with `expected`, `confidence` and a probability per value | Not in the documented API as reviewed (October 2026) |
| Streaming decisions | Sessions over a WebSocket (announced, not yet served): the context sent once, one typed reply per frame | Not in the documented API as reviewed (October 2026), which describes request and response calls |
| Input | Text, JSON and images (`images` field) | Documented as text only, with no image, audio or video input |
| Context | 64k tokens per request (65,536) | Documented as 64k tokens per request and 32k tokens for `state` plus the longest question |
| Price per 1M input tokens | $0.042 (DecisionNode-1.0), $0.021 (DecisionNode-1.0 Flash, provisional) | Documented as $0.042 |
| Output tokens | Free | Documented as free |
| Model ids | `decisionnode-latest`, `decisionnode-flash-latest`, pinned versions such as `decisionnode-1.0` | Documented aliases `jev-latest` (pointing to `jev-1.13.0`) and `jev-preview` |
| Default rate limits | 40 requests and 100,000 input tokens per second (provisional) | Documented as 100K tokens and 40 requests per second, subject to change |
| Client libraries | Plain HTTPS; these docs show curl, Python and TypeScript | Python and JavaScript SDKs are documented |

## What differs

- **Truth and `noul`.** DecisionNode calls the probability type `truth`: is this statement true, as one calibrated probability from 0.00 to 1.00. A question sent as `"type": "noul"` is the same type under its old name: it is accepted unchanged and answered as `{ "type": "noul", "noul": 0.94 }`, so code that reads `answers.<key>.noul` keeps working. Switch to `truth` when you next touch the code. See [Truth](https://decisionnode.com/docs/concepts/truth).
- **Images.** DecisionNode accepts an optional `images` array next to the state. Requests without it are unaffected. See [Images](https://decisionnode.com/docs/concepts/images).
- **Number questions**. A fourth question type, `number`, answers how many or what value on a grid you set. It is an addition: requests that use only `choice`, `score` and `noul` or `truth` are unaffected. See [Number](https://decisionnode.com/docs/concepts/number).
- **Sessions** (announced, not yet served). For more than 10 decisions a second, a session keeps the context loaded and streams one reply per frame. `/v1/decide` itself is unchanged. See [Sessions](https://decisionnode.com/docs/api/sessions).
- **Two tiers.** `decisionnode-flash-latest` is a compact, faster tier on the same API at a lower price per token (provisional). See [DecisionNode-1.0 Flash](https://decisionnode.com/docs/models/flash).
- **Formulas.** These docs publish both confidence formulas, one for choice and one for score, so you can reproduce every confidence from `probabilities`. See [Confidence](https://decisionnode.com/docs/concepts/confidence).
- **SDKs.** If your code uses TypeSafe AI's SDKs rather than raw HTTP, the SDK's own client handles the URL and errors. Replace the calls with plain HTTPS as shown in the [quickstart](https://decisionnode.com/docs/quickstart), or wrap them in a small function of your own.

## Test before you switch

1. Collect a few hundred real requests with known outcomes.
2. Send each one to both APIs and store the answers side by side.
3. Compare accuracy and the share of answers above your thresholds on your own data.
4. Re-tune thresholds on DecisionNode before you cut over. Probabilities from different models are not interchangeable, even when the shapes match.

> **Try one of your own requests now** Paste a request body you already send into the [playground](https://decisionnode.com/playground) in JSON mode and run it against both DecisionNode models.

## Choose DecisionNode when

- Your decisions involve images as well as text, such as receipts, documents or product photos.
- You want a lower-priced tier for high-volume, clear-cut decisions.
- You want to keep your existing request bodies and compare results on your own traffic.

## Choose Jev when

- Your integration depends on TypeSafe AI's Python or JavaScript SDKs and you prefer to keep them.
- You rely on parts of TypeSafe AI's platform that this page does not cover.
- Your own evaluation on your data favors its answers for your questions.

## Methodology and sources

This comparison is based on publicly available information from each provider's official documentation as reviewed on 4 October 2026. Features, pricing and availability may change. Verify current details directly with each provider before you decide. DecisionNode is an independent service and is not affiliated with, sponsored by, or endorsed by TypeSafe AI. All third-party names and trademarks are the property of their respective owners and are used only to identify the products being compared.

Sources:
- [TypeSafe AI docs: HTTP API reference](https://docs.typesafe.ai/api.md)
- [TypeSafe AI docs: Models](https://docs.typesafe.ai/models.md)
- [TypeSafe AI docs: index](https://docs.typesafe.ai/llms.txt)