# DecisionNode

> DecisionNode is a decision engine: send it text, JSON or images with a question, and it answers with calibrated probabilities, in milliseconds, through one API.

A System One model is a class of AI model that returns typed, probabilistic decisions from a fixed answer space instead of generating text. Given a piece of state and a set of questions defined in code, it answers each one with a schema-valid value such as a chosen option, a score, or a probability, and then stops. DecisionNode is a System One decision model behind one HTTPS endpoint, `POST https://api.decisionnode.com/v1/decide`: it reads a state (text, JSON or images) and answers typed questions in one pass, with no deliberation: a choice among options, a score on a scale, the probability that a statement is true, or a number. Every answer carries calibrated probabilities. It never generates text, which makes it the right tool for routing, triage, moderation, scoring and gating and the wrong one for writing. Made by Bynn Intelligence, Inc.

## For coding agents: the integration contract

To set up DecisionNode in a project, fetch and follow the setup guide: https://decisionnode.com/agent-setup.md (the key, the docs MCP server, the call, the rules and a check). The block below is the contract it carries; follow it as written.

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 that key to a browser, an app or a device, and never log it. The API refuses browser (cross-origin) calls except with a publishable key, so frontend code calls this app's own backend, which calls DecisionNode; a device gets a Decisions-only key of its own from the app's server.

Request body (questions required; model, state, images and boosters optional; model defaults to "decisionnode-1.0"; a field sent as null equals one left out):
{
  "model": "decisionnode-1.0",  // or "decisionnode-1.0-flash", or the workspace's fine-tuned model "decisionnode-1.0@acme/fraud"
  "fallback": true,  // default; when DecisionNode MoE has no ready capacity, DecisionNode Flash answers (body "model" and header x-decisionnode-fallback say so, billed at DecisionNode Flash's price); false = a 529 to retry instead
  "state": "<text>" | { ...json },
  "images": [{ "id": "photo", "media_type": "image/jpeg", "data": "<base64>" }],  // up to 16; or { "id": "photo", "url": "https://..." }
  "boosters": ["age", "ai_generated"],  // optional, up to 4, each once; specialist readings of every image, priced per picture read (`age` (Human Age) $0.024, `ai_generated` (AI-generated) $0.006, `face_detection` (Face detection) $0.001, `face_recognition` (Face recognition) $0.001 on your own collection and $0.001 on `celebrities`, `ocr` (OCR) $0.0015, `bynn_depth` (Depth Vision) free, `bynn_segment` (Segment Vision) $0.001 and `knowledge` (Knowledge) $0.001 a request). An entry may instead be { "name": "ai_generated", "images": ["photo"], "require": true } to narrow the images it reads or to fail the request (529) without it, or with "timeout_ms" (100 up to the booster's ceiling) to set its time budget for the request. The knowledge booster reads your own stored documents instead of images: { "name": "knowledge", "options": { "collection": "<knowledge base id>" } }, $0.001 a request; its passages come back cited in evidence.knowledge (docs: /docs/knowledge)
  "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>" },  // needs instructions or criteria
    "<key>": { "type": "number", "instructions": "<what to count or read>",
      "min": 0, "max": 50 },
    "<key>": { "type": "point", "instructions": "<what to find>" }  // or "box"; needs an image; "image": "<id>" with two or more
  }
}
With two or more images, say in each question which image it is about: by id in backticks (preferred; give images short names such as "receipt", not digits, and an id stays right when images are reordered), or by number from 1 in array order ("image 2", "the second image"). Videos work the same way, numbered separately ("video 1"). The point and box "image" field takes the id, never a number.

Response:
{ "model", "answers": { "<key>": answer },
  "usage": { "input_tokens", "output_tokens": 0,
             "cost": { "usd", "model_usd", "boosters_usd", "free_tier" } } }  // what the answer booked, in USD
With boosters, also "evidence": { "<booster>": { "version", "status": "ok" | "timeout" | "error" | "skipped", "latency_ms", "results": [{ "image": "<id>", ... }] } } (on "timeout" or "error", results list bare { "image" } entries and billed_calls is 0; a picture the booster cannot decode is { "image", "readable": false }, not billed) and usage.booster_tokens and usage.boosters (calls billed). age results: age_years, low, high, confidence, faces. ai_generated results: generated, confidence, method ("inference" | "c2pa": trusted Content Credentials declare it AI-made), top_generator ({ name, probability } only when an inference reading says likely generated, else null), c2pa_signer (for trusted credentials, else null), and c2pa: "untrusted" only when the file's credentials validate but are not trusted (no signer, no override). A booster never answers a question: read the answers, and log evidence with the decision.
- 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" }
- point:  { "x", "y", "present", "confidence", "image", "width", "height" }  // pixels from the top-left corner
- box:    { "x1", "y1", "x2", "y2", "present", "confidence", "image", "width", "height" }

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), on the truth probability, or on present (point, box: their confidence is not calibrated yet, so never gate on it). 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). Exception: if the decision is about a person in hiring, credit, housing, insurance, education, benefits, law enforcement or healthcare, route it to a qualified human reviewer before it takes effect; if it concerns a vehicle, drone, robot or machine, feed the answer to the system's own controller and never act on it directly.
3. On 429 and 529 wait for retry-after-ms (or Retry-After, in seconds), then retry with exponential backoff and jitter. Every 5xx, a 408 and a client timeout (10 s per attempt) are safe to retry, except a request naming the ocr booster: give it 30 s per attempt and never retry it after a timeout, since the attempt may still be billed. Do not retry 400, 401, 402, 403, 413 or 422; fix the key or the body (the x-decisionnode-error header says what is wrong). A 403 is a safety refusal (error_type "refusal_error", with a "category") or a paused workspace (error_type "workspace_suspended"); neither is billed. A 402 (error_type "insufficient_credit") means the prepaid balance is empty: alert, and send again only after credit is added. Boosters: 400 "booster_unknown" (a name that is not a booster), 400 "booster_input_mismatch" (a booster on a request without images, or an images id not in the request), 400 "api_usage_error" (a malformed boosters array) and 403 "booster_not_enabled" (turned off for the workspace) are fixed in code or the console, never retried; 529 "booster_unavailable" (a required booster failed) is retried like any 529. Sessions take no boosters. A fine-tuned model name that is unknown, not deployed or another workspace's is the 400 "Unknown model: <name>".
4. Pin a version such as "decisionnode-1.0" (for a fine-tuned model, "decisionnode-1.0@acme/fraud:3") where answers must not change across releases; the response's "model" names the version that answered.
5. Write a test that posts a fixed request and asserts the answer keys and types.
6. Read the response's "model" (the model that answered) and log it with the decision. A DecisionNode MoE request may be answered by DecisionNode Flash when DecisionNode MoE has no ready capacity; send "fallback": false where the decision must come from DecisionNode MoE (a re-check of an unsure DecisionNode Flash answer), and retry its 529. Only live /v1/decide calls for DecisionNode MoE fall back; DecisionNode Flash, fine-tuned models, sessions and batch lines never do, and a fine-tuned model that was idle may answer 529 for a few minutes until it is ready: retry after Retry-After.

## Key facts

- API base: https://api.decisionnode.com. Endpoints: `POST /v1/decide` (ask questions), `GET /v1/models` (https://api.decisionnode.com/v1/models), `POST /v1/uploads` (put an image in storage once and name it by `upload_id` for an hour, https://decisionnode.com/docs/api/uploads), `POST /v1/sessions` (streaming decisions over a WebSocket, https://decisionnode.com/docs/api/sessions) and `POST /v1/batches` (batch jobs, https://decisionnode.com/docs/api/batches).
- Authentication: `Authorization: Bearer <key>`; keys start with `dn_live_` and are created in the console at https://decisionnode.com/console/keys. Keep a Full access key in the `DECISIONNODE_API_KEY` environment variable on a server; only a Publishable key goes in a browser or an app.
- API keys (https://decisionnode.com/docs/concepts/keys): four kinds, set when the key is made and never changed. Full access (`full`, every key made before the kinds): everything, on your servers only. Decisions only (`decide`): `POST /v1/decide` and `GET /v1/models`, no uploads, sessions, batches, or collections, `face_recognition` only with `may_search_collections`; one per device, with its own `device_id`, `labels` (`{"name": "value"}`), `limits` (`requests_per_second`, `tokens_per_second`), `daily_spend_cap` (`{"usd"}` a day, with `spent_today`) and optional `expires_at` (expired: `401` with `details.reason` `key_expired`; provision again, never retry). Manage device keys (`keys`): only `/v1/keys`, on your provisioning server, to make (`POST /v1/keys` with an `Idempotency-Key`; the secret once, in `{key, secret}`; a retry replays it only to the key that made it, another key or body getting `409` `idempotency_key_reused`, a revoked one `409` `key_not_replayable`), list (`GET /v1/keys` with `label=name:value`, `device_id`, `status` active, expired, revoked or all, cursor paging; there is no GET of one key by id), change and revoke Decisions-only keys, one by `DELETE /v1/keys/{id}` or a group by `POST /v1/keys/revoke` with `{"labels": {...}}` (`dry_run` to count; at most 10,000 a call; call again while `more` is true, which it can be with fewer left) (https://decisionnode.com/docs/patterns/device-keys, https://decisionnode.com/docs/api/keys). Per-key usage, to bill each device's owner: `GET /v1/keys/{key_id}/usage` (one key; `start` and `end` default to the current UTC month so far) and `GET /v1/usage` (`{period, as_of, items, next_cursor}`, one row per key, newest first; `start` and `end` required; `label=name:value` repeated and read from the key's labels as they are now, `device_id`, `key_id` up to 100, `scope` full, decide or keys, `status` all by default so revoked and expired keys are included, `include_empty`, `limit` up to 1,000 or 100 with buckets; a page reads at most 150,000 hourly rows, so it can hold fewer keys: follow `next_cursor` to `null`), with a Full access or Manage device keys key: `start` rounded down and `end` up to the hour, `end` exclusive, at most 400 days, usage kept indefinitely; `granularity` none, hour (up to 7 days), day or month adds `buckets` with usage; `group_by` model or channel (`by_channel` always lists live, batch and session); `totals` has `requests` (every call, refused and failed ones included), `free_tier_requests` (at no cost), `input_tokens` (image and video included), `image_tokens`, `video_tokens`, `booster_calls` and `cost` (`usd`, `model_usd`, `boosters_usd` in whole micro-dollars: what the workspace is charged, the same as its invoice's usage, its console usage page and each answer's `usage.cost`); `as_of` never passes the period's end, and the figures are final once it equals it, so invoice then; a key the caller cannot read is `404` `not_found_error`, never `403`; 10 reads a second per workspace for both routes, one at a time (`529` after a second's wait) (https://decisionnode.com/docs/patterns/bill-per-device, https://decisionnode.com/docs/api/usage). Publishable (`publishable`, `dn_pub_` keys, console only): public by design, for browsers (exact allowed origins, `https://host[:port]`, `http://` only for localhost; a preflight is answered only for `POST /v1/decide`, from a listed origin; an origin the key does not list is `403` `origin_not_allowed`; a page can read `x-request-id`, `retry-after`, `retry-after-ms`, `x-decisionnode-cache` and `x-decisionnode-model`) and apps (no `Origin`, only with Allow native apps; without origins its limits are its only protection), `POST /v1/decide` only, not even `GET /v1/models` (`403` `key_scope_denied`, "A publishable key may only make decisions."), on the models it lists (`403` `model_not_allowed` with `details.allowed`; DecisionNode Flash by default and a body without `model` asks DecisionNode MoE, so name `model`; never a fine-tuned model), a `429` per client address (an IPv6 visitor by its /64; `details.reason` `client_rate`) and for calls in flight (`in_flight`), a fallback only to one of its models; only a publishable key's answers carry the CORS headers, so no other key works in a page, never a face search, rate limits and a daily spend cap always on (https://decisionnode.com/docs/patterns/publishable-keys). Never put a Full access or Manage device keys key on a device or in a browser. A call outside a key's kind is `403` `key_scope_denied`; past the daily spend cap, `429` `key_spend_cap_reached` until 00:00 UTC.
- SDKs (https://decisionnode.com/docs#how-to-call): Python `bynn-decisionnode` (`pip install bynn-decisionnode`, https://github.com/Bynn-Intelligence/decision-node-python), TypeScript and JavaScript `@decisionnode/sdk` (`npm install @decisionnode/sdk`, https://github.com/Bynn-Intelligence/decision-node-node), Go `github.com/Bynn-Intelligence/decision-node-go` (`go get github.com/Bynn-Intelligence/decision-node-go`, https://github.com/Bynn-Intelligence/decision-node-go), Java and Kotlin `com.bynn:decisionnode` (`implementation("com.bynn:decisionnode:0.3.2")`, https://github.com/Bynn-Intelligence/decision-node-java), C# and .NET `Bynn.DecisionNode` (`dotnet add package Bynn.DecisionNode`, https://github.com/Bynn-Intelligence/decision-node-dotnet), PHP `bynn/decisionnode` (`composer require bynn/decisionnode`, https://github.com/Bynn-Intelligence/decision-node-php). Each reads `DECISIONNODE_API_KEY`, sends the same `POST /v1/decide`, parses the answers into types and retries temporary errors. Coming soon, with no package yet: Ruby, Rust.
- MCP server (https://github.com/Bynn-Intelligence/decision-node-mcp-server): DecisionNode's questions as tools for an agent (`truth`, `choice`, `score`, `number`, `point`, `box`, `decide`, `decide_many`, `decide_video`, `models`, `guide`), each call a request with the user's own key. Run it with uv, `uvx bynn-decisionnode-mcp`, the key in its environment as `DECISIONNODE_API_KEY`; or as Streamable HTTP, `uvx bynn-decisionnode-mcp --transport http --host 0.0.0.0 --port 8000`, each client sending its own key. It is not the docs MCP server at https://decisionnode.com/mcp.
- Integrations: Home Assistant (https://decisionnode.com/docs/integrations/home-assistant, https://github.com/Bynn-Intelligence/decision-node-home-assistant): questions about your cameras in automations, sensors and Frigate events; MQTT bridge (https://decisionnode.com/docs/integrations/mqtt, https://github.com/Bynn-Intelligence/decision-node-mqtt): decisions for any device that can publish to an MQTT broker; ROS 2 (https://decisionnode.com/docs/integrations/ros2, https://github.com/Bynn-Intelligence/decision-node-ros2): a node that asks your questions about an image topic and publishes the answers.
- Command line (https://decisionnode.com/docs/cli): `dn` asks the same questions from a shell or a script (`dn truth`, `dn choice`, `dn score`, `dn number`, `dn decide <request.json>`, `dn upload`, `dn session`, `dn batch`, `dn models`), prints JSON in a pipe and exits with a code per outcome. Install: `curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/Bynn-Intelligence/decision-node-cli/main/install.sh | sh` (macOS and Linux), `brew install bynn-intelligence/bynn/dn`, or `scoop install dn` after `scoop bucket add bynn https://github.com/Bynn-Intelligence/scoop-bynn` (Windows). It reads `DECISIONNODE_API_KEY` first, then the key `dn auth login` stored.
- Models: `decisionnode-1.0` (DecisionNode MoE, pinned version `decisionnode-1.0`, $0.042 per million input tokens) and `decisionnode-1.0-flash` (DecisionNode Flash, pinned version `decisionnode-1.0-flash`, $0.035 per million input tokens). Output tokens are free: the API answers with numbers, not text. Image and video tokens: $0.09 per million on DecisionNode MoE and $0.08 on DecisionNode Flash, no per-image fee. Batch jobs are 30% off the live price on DecisionNode MoE and 50% off on DecisionNode Flash ($0.0294 and $0.0175 per million input tokens). A price change applies to usage from its date; one scheduled within 30 days is shown beside its price as "from" a date (https://decisionnode.com/docs/pricing). When DecisionNode MoE has no ready capacity, a request for it is answered at once by DecisionNode Flash, billed at DecisionNode Flash's price, with the body's `model` and the headers `x-decisionnode-fallback` and `x-decisionnode-requested-model` saying so; `"fallback": false` in the request (or a workspace fallback policy of `never`) gives a 529 with `Retry-After` instead. Only live `POST /v1/decide` calls for DecisionNode MoE fall back: DecisionNode Flash, fine-tuned models and session opens answer 529 with `Retry-After`, and batch lines wait in the batch's queue. A fine-tuned model that has not been called for a while can take a few minutes to become ready; retry its 529 after `Retry-After`. A workspace's own fine-tuned models are named `<base>@<workspace>/<name>` (the version deployed most recently) or `<base>@<workspace>/<name>:<n>` (one version), for example `decisionnode-1.0@acme/fraud`; only that workspace's keys can send them, and the response's `model` is always the pinned name.
- Limits per request: 64k tokens of context, up to 16 images of 10 MB each (base64 `data`, an `https` `url` or an `upload_id`), up to 255 options in a choice, up to 10 levels in a score, up to 4 boosters, a body of at most 25 MiB (inline base64 images count toward it; uploads and URLs do not, so send large images as uploads).
- Question types: `choice`, `score`, `truth` (the probability that a statement is true), `number` (a value on a grid you set), `point` and `box` (where in an image). Two new question types answer where: point gives one spot in the image, box draws a rectangle around the thing. You get coordinates you can draw, crop or hand to a machine, and every answer says how likely the thing is there at all and how likely the place is right. A point's or box's `confidence` is not calibrated yet (a correct place can read low): act on `present`. Sessions take no point or box questions. Shapes: https://decisionnode.com/docs/concepts/points-and-boxes.
- Referring to images and videos: with two or more images, say in each question which image it is about, by `id` in backticks (recommended; give images short names such as `receipt`, not digits) or by number from 1 in the order of `images` ("image 2", "the second image", "Picture 2", "the last image"). Each image is introduced as `Picture 1 (receipt):`, so both point to the same image. Videos work the same way, numbered separately ("video 1"). The point and box `image` field takes the id (https://decisionnode.com/docs/concepts/images#referring-to-images-and-videos).
- Video: up to 4 videos and 128 frames per request, sent as frames with timestamps and read as one video with order and timing (https://decisionnode.com/docs/concepts/video). Frames only: no video files or URLs; the `dn` command line (`--video PATH`) turns a local file into frames on your machine.
- Cost of an answer: every answer's `usage.cost` is `{"usd", "model_usd", "boosters_usd", "free_tier"}`, what it booked in USD at the workspace's rates (`usd` = `model_usd` + `boosters_usd`, up to 9 decimals); `free_tier` is true when the free tier covered the model's request; a refused or unbilled answer has every amount 0; batch result lines, session opens and frames carry their own; no header carries it (https://decisionnode.com/docs/pricing#answer-cost).
- Boosters (https://decisionnode.com/docs/concepts/boosters): specialist models that read a request's images before the decision; the model still answers every question. List up to 4 by name in a top-level `boosters` array, `"boosters": ["age", "ai_generated"]`, each reading every image (an entry may instead be an object, `{"name": "ai_generated", "images": ["photo"], "require": true}`, to narrow the images it reads or to fail the request without it): `age`, Human Age: Estimates a person's age from a face in the picture, using the [agemin.com](https://agemin.com) age estimation model, ranked #1 by NIST for Child Online Safety (ages 13 to 16) on true positive rate. [View the NIST report card](https://face.nist.gov/fate/reportcards/aev/bynn_000.html) · [NIST results](https://pages.nist.gov/frvt/html/frvt_age_estimation.html). `ai_generated`, AI-generated: Whether a picture was made by an image generator, and which kind, using Trinity, the state-of-the-art AI image detection model from [detector24.ai](https://detector24.ai). `face_detection`, Face detection: Finds the faces in a picture: how many it shows and where each one is, with a box and a confidence per face, from Bynn's face detection model. `face_recognition`, Face recognition: Matches the faces in a picture against a collection: one of your own, enrolled through the API or the console, or the public celebrities collection. Each match carries a score and the item's reference, with your label or the public figure's name, and never a picture. `ocr`, OCR: The text a picture shows, read by Bynn OCR: all of it by default, or what a prompt asks for, such as a formula in LaTeX, a table in HTML or Markdown, or the fields of a JSON schema. Full support for English and Chinese; other languages need a prompt that names them. `bynn_depth`, Depth Vision: Distance in meters to what's in the picture: the nearest obstacle straight ahead, seven directions from left to right, and a grid of up to 16 by 16 cells. `bynn_segment`, Segment Vision: Finds what you name in words in the picture: each match's outline, box and centre, and with depth on, its distance and size in meters. `knowledge`, Knowledge: Applies your own documents: the passages of one of your knowledge bases that fit the request are read with it as facts and rules, and cited in the answer's evidence. Readings come back in `evidence` (per booster: `version`, `status` ok, timeout, error or skipped, `latency_ms`, `billed_calls`, `results` per image; a timed-out or failed booster lists bare `{"image"}` entries and bills nothing, a picture it cannot decode is `{"image", "readable": false}` and is free, a reading that finds nothing is billed: a Human Age picture with no face is `{"image", "faces": 0}`, Face detection's `"faces": 0, "detections": []`, Face recognition's `"matches": []`, OCR's empty `text`), with `usage.booster_tokens`, `usage.boosters` and the `x-decisionnode-boosters` header (`age=ok:212,ai_generated=timeout:800`). Each booster has a time budget, 2 s for `age`, 5 s for `ai_generated`, 2 s for `face_detection`, 2 s for `face_recognition`, 12 s for `ocr`, 800 ms for `bynn_depth`, 1.5 s for `bynn_segment` and 800 ms for `knowledge`, and a booster object's `timeout_ms` sets it for one request, from 100 ms up to the booster's ceiling (2 s up to 5 s for `age`, 5 s up to 6 s for `ai_generated`, 2 s up to 5 s for `face_detection`, 2 s up to 5 s for `face_recognition`, 12 s up to 12 s for `ocr`, 800 ms up to 5 s for `bynn_depth`, 1.5 s up to 5 s for `bynn_segment` and 800 ms up to 5 s for `knowledge`; outside that, a `422` and nothing runs); they run side by side, and a request naming `ocr` wants a client timeout of 30 s per attempt and no retry after a timeout. A request's readings take at most 256 KiB, 1 MiB when it names `ocr`, `face_recognition` or `bynn_segment`, and one `ocr` reading at most 128 KiB of text; a booster whose readings do not fit is that booster's unbilled `error` for all its pictures, and the decision runs with the readings that fit. Settings go in an object's `options`: `ocr` takes `prompt` (at most 2,000 characters; default `"Text Recognition:"`, also `"Formula Recognition:"` and `"Table Recognition:"`, or your own instruction or a JSON schema). `face_recognition` takes `collection` in `options` (required: `celebrities`, or the id of one of your own collections) and `threshold` (0 to 1, default 0.5), and returns per picture `{"image", "faces", "collection_name" (own collections), "matches": [{"box", "score", "collection", "collection_name", "reference", "label" | "name"}]}`. `bynn_segment` takes `prompt` in `options` (required: a phrase, or 1 to 4 phrases of at most 120 characters; `|` and control characters become spaces, repeats are dropped), `max_instances` (1 to 16, default 8), `min_score` (0 to 1, default 0.25), `polygon_points` (3 to 64, default 24) and `depth` (default true), and returns per picture `{"image", "width", "height", "prompts", "instances", "depth_source", "assumed_hfov_deg"}`, each instance `{"label", "score", "box", "polygon", "area", "centroid", "opening", "depth", "size_m"}` by score: coordinates are fractions 0 to 1 from the top left after EXIF orientation, `opening` the enclosed hole of a gate, doorway or ring or `null`, `depth` meters along the camera axis (`median`, `opening_median`, `opening_rim_median`), `size_m` at an assumed 65-degree horizontal field of view; one call per picture read, depth included; descriptive phrases match better than short ones ("purple octagonal frame on a pole" finds what "purple gate" misses), and gates and doorways often come back as one filled shape for now, `opening` `null`; a bad option is the `400` `api_usage_error` with the reason in `x-decisionnode-error` (such as `"options": 'prompt' is required`); distances and sizes are estimates from one picture, for decisions and planning, never a safety stop. `bynn_depth` takes `grid_size` in `options` (2 to 16, default 8) and returns per picture `{"image", "ahead", "directions", "ground", "grid_rows", "grid_cols", "grid", "depth_min", "depth_max", "depth_median", "width", "height"}`, distances in meters: `ahead` the nearest obstacle in the middle third of the picture and `directions` the same in 7 strips left to right (each `null` when none is found), the floor or ground left out when `ground` is true, `grid` row by row from the top left, each cell its median distance; they are estimates from one picture, for decisions and planning, never a safety stop (robots use stereo or LiDAR for that). Face boxes are `{"x1", "y1", "x2", "y2"}` in the request's units (pixels unless every point and box question asks for `units: "normalized"`). Priced per picture read, by booster: `age` (Human Age) $0.024, `ai_generated` (AI-generated) $0.006, `face_detection` (Face detection) $0.001, `face_recognition` (Face recognition) $0.001 on your own collection and $0.001 on `celebrities`, `ocr` (OCR) $0.0015, `bynn_depth` (Depth Vision) free, `bynn_segment` (Segment Vision) $0.001 and `knowledge` (Knowledge) $0.001 a request, counted per booster in `evidence.<name>.billed_calls`; a reading is billed every time a request uses it, also when the workspace's cache of readings answers it (an hour at most, per workspace, never under zero retention, never for `face_recognition`); a timed-out, failed or skipped booster, a picture it cannot decode and a refused request bill nothing. On `/v1/decide` and batch lines; sessions take none.
- Fine-tuning (https://decisionnode.com/docs/fine-tuning): a workspace trains its own version of DecisionNode MoE or DecisionNode Flash in the console from 200 to 50,000 labelled records (JSON Lines: a request as `/v1/decide` takes it plus `answers`, optional `weight` and `split`; images as a live `upload_id` or inline `data`, never a `url`; up to 64 MiB). A quality gate ships a version only if it beats the base on held-out records (accuracy at least 0.02 higher with a gain whose interval lies above 0, calibration error at most 0.01 higher, standard test sets at most 0.01 lower, same refusals); otherwise `no_gain`. A run costs 3 × its compute time + $50, $50 on `no_gain`, the compute so far without the $50 when cancelled, nothing when it fails or the safety check refuses records before training; requests cost the base's price + $0.02 per million input tokens. Deployed versions are listed at `GET /v1/models` with `fine_tuned`, `base`, `adapter_version` and `status`. Records can be written from your own system or labelled in the console from requests the workspace kept: with the opt-in setting "Keep requests for labelling" on (not under zero retention), answered `/v1/decide` requests are kept 30 days with their uploaded and inline images (not images sent by URL), encrypted, in the workspace's storage location, and deleted when it is turned off.
- Repeated requests: the same `/v1/decide` request (same model, body byte for byte, opt-in headers; a family is cached under its family and a repeat names the version that answered it, so shortly after a release it may carry the previous version's answer, labelled with that version; a pinned version is cached under itself) from the same API key within 120 seconds is answered from a cache, in milliseconds, with `x-decisionnode-cache: hit` (`miss` when the cache was looked up and held nothing, `bypass` when it was not looked up; the header is on every `/v1/decide` response; stored answers live on the server that answered), and billed in full; pictures match by content (an upload by the SHA-256 checksum sent with it, so the same picture uploaded twice is the same; an upload without a checksum is never cached); requests with `url` images, zero-retention workspaces, non-200 answers, fallback answers, per-question refusals and answers over 256 KiB are never cached, and sessions and batch lines never use it; the request header `x-decisionnode-cache: bypass` skips the lookup (https://decisionnode.com/docs/api/decide#repeated-requests).
- Errors: 400 bad request (`api_usage_error`, also an unknown model, a fine-tuned name that is not deployed or another workspace's, and a malformed `boosters`; `booster_unknown`; `booster_input_mismatch`; `max_tokens_exceeded`), 401 bad key, 402 out of credit, 403 refused (`refusal_error`, `workspace_suspended`, `booster_not_enabled`, `key_scope_denied`), 422 bad body (fix, do not retry), 429 over the rate limit (the workspace's, shared by its keys, by default 40 requests and 100,000 input tokens a second, or a key's own lower limit; wait `Retry-After`; `key_spend_cap_reached` is a key's daily spend cap: do not retry before it resets), 529 overloaded, a DecisionNode MoE request that opted out of the fallback while it has no ready capacity, or a required booster failed (`booster_unavailable`; retry with backoff). Full table: https://decisionnode.com/docs/api/errors.
- Free tier (https://decisionnode.com/docs/pricing#free-tier): The first workspace you create has a free tier, renewed at 00:00 UTC every day: 50 DecisionNode Flash requests, 20 DecisionNode MoE requests and 10 booster calls, the booster calls shared across all boosters. It covers every live decision, on `/v1/decide` and the OpenAI-compatible route, from the playground and from API keys alike; batches, sessions and fine-tuned models are billed normally. A request counts against the model it asks for: a DecisionNode MoE request answered by DecisionNode Flash on a fallback uses one of the DecisionNode MoE requests. A request within its count costs nothing and is marked `free_tier` in your usage. Past a count, requests are billed from the prepaid balance, and when the balance does not cover one, the API answers `402` naming the count and when it renews. Later workspaces have none, a workspace created after deleting the first one included, and neither do workspaces you are invited to or dedicated ones.
- Try it with a free account and no key: https://decisionnode.com/playground runs the request shapes in the browser, on your own workspace.
- Referral program (Refer & earn, a beta): every signed-in user has a referral link (`https://decisionnode.com/?ref=<code>`) and a code in the console; the developer referred gets $5 off their first top-up of $10 or more, and after 25 qualified referrals the referrer earns 12% in cash of each referred workspace's usage during its first 6 months. How it works: https://decisionnode.com/docs/refer-and-earn. Terms: https://decisionnode.com/legal/affiliate-program-agreement.
- Collections (https://decisionnode.com/docs/concepts/collections): stored faces a request is matched against. `POST /v1/collections` creates a `face` collection for the workspace; `POST /v1/collections/{id}/items` enrolls one face per picture (`image`, your `reference` up to 64 characters, an optional `label` up to 128; the largest face is taken, a picture with no face an enrollment can take is a billed `422` `no_face`, a picture that cannot be read, more than 1,024 faces included, an unbilled `422` `image_unreadable`; an optional `Idempotency-Key` header makes a retried create or enrollment run and bill once); items are listed (`offset`, `limit` up to 100, or by `reference` or `reference_prefix` in reference order with `total_capped` past 10,000), edited with `PATCH /v1/collections/{id}/items/{item_id}` (`reference`, `label` or `null`, `metadata` replaced whole; never billed, with an optional `Idempotency-Key`) and deleted under the same path; an item may carry `metadata`, up to 20 flat fields (text, number or boolean) and 4096 bytes, returned on a match of your own collection and read by the model (https://decisionnode.com/docs/api/collections/enroll#metadata). A match's `collection_name` is your collection's name (its `col_` id when it has none) or a public collection's id, and a search of your own collection also carries `collection_name` on the picture's result; both only on dn-evidence-4 readings, so optional. The model reads it, so a question may name the collection ("Is this person in our staff collection?"). Only the face template is kept, never the picture, and a collection is visible to its workspace only. One public collection, `celebrities` (every workspace; a match returns the public figure's `name`). Search with the `face_recognition` booster, `{"name": "face_recognition", "options": {"collection": "<id or public name>", "threshold": 0.5}}`: per picture `{"image", "faces", "collection_name" (own collections), "matches": [{"box", "score", "collection", "collection_name", "reference", "name" | "label"}]}`, up to 64 faces searched and 64 matches a picture; a picture with more than 1,024 faces fails the booster (`error`, unbilled); its readings are never cached. Prices: a search $0.001 a picture of an own collection, $0.001 of `celebrities`; an enrollment $0.001 once the face model reads the picture, a face found or not; storage $0.00001 per item and month, a monthly fee (an item stored at any time in a month pays it, no proration), charged on the 1st; the free tier covers own and `celebrities` searches, never enrollment or storage; per workspace at most 100 collections and 1,000,000 items; an unpaid storage charge is retried 3 times 10 days apart, then the items are deleted 30 days after the third failure unless a top-up or a new payment method clears it. API: https://decisionnode.com/docs/api/collections.
- Knowledge (https://decisionnode.com/docs/knowledge): your own policies, rules and instructions, stored once in a knowledge base (a collection of type `text`) and given to the decisions that need them. `POST /v1/collections` with `{"type": "text", "name", "scope_key"?}` creates one; `POST /v1/collections/{id}/items` adds a document (`title` up to 200 characters, `text` Markdown or plain up to 512 KiB, `format` `markdown` or `text`, optional unique `reference`, `pinned`, `pin_rank`, `label`, `metadata`), answering `202` with `status` `queued` (then `processing`, `ready` or `failed`), or `?wait=true` up to 10 s for `201` ready; `PUT` replaces it (the old version serves until the new one is ready; the same text again is a free no-op), `PATCH` changes reference, label, metadata or pin without re-indexing, `GET .../items/{item_id}?include=text` returns the stored text, `GET .../items/{item_id}/chunks` its passages, `DELETE` removes it. A file (PDF up to 100 pages, DOCX, PPTX, XLSX, HTML, images, text, Markdown; up to 50 MB) is presigned with `POST /v1/uploads` and `"purpose": "knowledge"` (a Full access key), PUT, then added with `{"upload_id"}` in place of `text` (`title` defaults to the file name); the console takes files too. The file is deleted once its text is read. A document that fails for good stays listed with its `error`, counting toward nothing; `DELETE /v1/collections/{id}/items?status=failed` deletes them all. The list takes `?q=` and `?sort=newest|oldest|title`. Use it with the `knowledge` booster, object form only: `{"name": "knowledge", "require": true, "options": {"collection": "col_...", "scope"?, "top_k"? (default 4, 0 to 20, 0 pinned only), "max_tokens"? ("auto" or 128 to 8192), "match"?, "filter"?, "query"?, "pinned"?, "min_score"?, "include_text"? (Full access keys only)}}`; it reads the questions and state, never a picture (`images` on it is `400` `booster_input_mismatch`). Pinned documents always come (capped at 512 tokens a request by default), then the best-matching passages within the budget, at most 3 per document; a knowledge base with a `scope_key` gives a request its global documents plus those of `options.scope`. `evidence.knowledge.results[0]` has `passages` (`n`, `pinned`, `item`, `reference`, `title`, `heading`, `chunk`, `byte_start`, `byte_end` into the stored text, `tokens`, `score`, `rendered`), `warnings` (`scope_not_named`, `over_budget`, `budget_floor`, `pinned_filtered`), `omitted`, `budget` and `pending_items`; with `require`, a knowledge base with nothing ready yet is `529` (retry after `Retry-After`) and one with nothing ready or processing `409` `knowledge_collection_empty`. `POST /v1/collections/{id}/search` with `{"query", ...}` runs the retrieval alone. Prices: $0.001 a call (one per request, or per search), $0.10 per million newly indexed tokens, $0.00002 per passage a month; the free tier includes 200 stored passages and 250,000 indexed tokens a day. DecisionNode does not use the documents to train or evaluate its models. API: https://decisionnode.com/docs/api/collections/add-document.
- Docs over MCP: https://decisionnode.com/mcp (Streamable HTTP, no key) has two tools, `search_docs` and `read_doc`, over these docs. Documentation only; decisions go through the API (https://decisionnode.com/docs/mcp).

## Documentation

### Get started

- [Introduction](https://decisionnode.com/docs): DecisionNode is a decision engine: send it text, JSON or images with a question, and it answers with calibrated probabilities. The answers are typed and come back in milliseconds: a choice or a score with calibrated confidence, a Truth (the calibrated probability that a statement is true), or a number on your grid.
- [Quickstart](https://decisionnode.com/docs/quickstart): Get an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.
- [Command line](https://decisionnode.com/docs/cli): dn is DecisionNode's command line: install it, store your key once, and ask typed questions from your terminal or a script, with request files, uploads, sessions and batch jobs one command each.
- [Playground](https://decisionnode.com/docs/playground): The playground runs DecisionNode request shapes in your browser with a free account and no key. Build the state and questions, run them, read the answers, and copy the exact request as curl, Python or TypeScript.
- [Console, keys and members](https://decisionnode.com/docs/console): The console is where a workspace keeps its API keys, members, balance and usage. How keys are created, rotated and revoked, what each role may do, and what deleting a workspace means.
- [With coding agents](https://decisionnode.com/docs/coding-agents): DecisionNode is one HTTPS call, so a coding agent can write the integration for you once it knows the shape. Paste the one-line prompt below and the agent fetches our setup guide, or give your own agents a decide tool.
- [MCP server](https://decisionnode.com/docs/mcp): The DecisionNode docs are an MCP server at https://decisionnode.com/mcp. Connect your coding agent and it can search these pages and read any of them as Markdown while it writes your integration. No key and no sign-in.
- [Examples](https://decisionnode.com/docs/examples): Complete recipes you can start from: the problem, the request, the answer and the code that branches on it. Cameras and production lines first, then text: traffic, people, incidents, the sorting line, points and boxes, support, moderation, receipts and more.

### Concepts

- [State](https://decisionnode.com/docs/concepts/state): The state is the thing you are deciding about. It can be any text, a JSON object or a JSON array. It is read once per request and shared by every question.
- [Questions](https://decisionnode.com/docs/concepts/questions): Questions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a Truth (the probability that a statement is true), a number on your grid, a point in your image or a box around the thing.
- [Choice](https://decisionnode.com/docs/concepts/choice): A choice question picks exactly one option from the list you give and returns the probability of every option plus a confidence you can threshold.
- [Score](https://decisionnode.com/docs/concepts/score): A score question places the input on an ordered scale you define. It returns the expected level, the probability of every level and a confidence.
- [Truth](https://decisionnode.com/docs/concepts/truth): Is this statement true? One calibrated probability from 0.00 to 1.00 that the statement is true. 0.80 means true about 8 times in 10. Your code picks the cut-off: 0.50 for a plain yes or no, higher when acting on a false yes is costly. It is the simplest type and the one most gates are built on.
- [Number](https://decisionnode.com/docs/concepts/number): How many, or what value? One value on a grid you set (min, max and an optional step), with a calibrated probability for every value: the most probable value, the expected value and the confidence. A count in a photo, a year in a contract, the overdue invoices in a statement: one call, no text to parse.
- [Points and boxes](https://decisionnode.com/docs/concepts/points-and-boxes): Two question types that answer where: point returns one spot in an image as x and y, box a rectangle around the thing. Every answer says how likely the thing is there at all and how likely the place is right.
- [Images](https://decisionnode.com/docs/concepts/images): Send up to 16 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 and values.
- [Video](https://decisionnode.com/docs/concepts/video): Send the frames from a camera with their timestamps, ask typed questions, and get calibrated answers about what happens over time: how many cars passed, which way a vehicle turned, whether smoke appeared.
- [Boosters](https://decisionnode.com/docs/concepts/boosters): A booster is a specialist model that reads your request's images before the decision and hands its reading to the model as evidence. Name up to 4 in boosters: age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment and knowledge. The readings come back in evidence, and each booster is priced per picture it reads: Human Age $0.024, AI-generated $0.006, Face detection $0.001, Face recognition from $0.001, OCR $0.0015, Depth Vision free, Segment Vision $0.001 and Knowledge $0.001 a request.
- [Collections](https://decisionnode.com/docs/concepts/collections): A collection is a set of stored faces your requests can be matched against: your own, enrolled through the API or the console, or the public celebrities collection. The face_recognition booster searches one per request, and its matches come back as evidence.
- [Confidence](https://decisionnode.com/docs/concepts/confidence): Probabilities are calibrated per question type, so a threshold means what it says on the data we measure. This page explains what calibrated means, how to check it on your own data, and how to choose where to draw the line.
- [Determinism](https://decisionnode.com/docs/concepts/determinism): The same request to the same model version returns the same answer. There is no sampling and no temperature, so answers can be tested, cached and audited.
- [API keys](https://decisionnode.com/docs/concepts/keys): Four kinds of API key, from full access on your server to a publishable key in a browser: what each may call, where it belongs, and why every device gets a key of its own.

### Knowledge

- [Knowledge](https://decisionnode.com/docs/knowledge): Store your own policies, rules and instructions once, and let every decision that needs them read the passages that apply. Knowledge bases hold your documents; the knowledge booster finds the right passages for each request and cites them in the response.
- [Documents](https://decisionnode.com/docs/knowledge/documents): What a knowledge base holds and how documents get into it: writing text, adding files through the API or the console, the formats and limits, a document's status, pinned documents and scope.
- [Knowledge in a decision](https://decisionnode.com/docs/knowledge/decisions): The knowledge booster on a request: its options, filters, what require guarantees, the token budget, and the citations it returns in evidence.knowledge.
- [Knowledge pricing, deleting and exporting](https://decisionnode.com/docs/knowledge/pricing): What knowledge costs: a price per call, per million tokens indexed and per passage stored a month, with a free allowance on the free tier. And how to export or delete your documents.
- [When a rule does not appear](https://decisionnode.com/docs/knowledge/troubleshooting): Why a passage you expected was not given to the model, read from evidence.knowledge, and what to change: the document's status, scope, filters, the budget, and how the request searches.

### Models

- [DecisionNode MoE](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 Flash](https://decisionnode.com/docs/models/flash): The compact, fastest tier. Same API and answer shapes as DecisionNode MoE, chosen with the model field, at $0.035 per million input tokens.
- [Limits](https://decisionnode.com/docs/models/limits): Context size, image and booster limits, question limits, body limits, session and batch limits, and the default rate limits. These apply to both models, and to fine-tuned models built on them.
- [Versions and retirement](https://decisionnode.com/docs/models/versions): Family ids move to each new release; pinned ids never change. A pinned version stays available for at least 12 months after its successor ships, and you get at least 12 months' notice before it retires.
- [Dedicated capacity](https://decisionnode.com/docs/models/dedicated): Capacity on our own GPUs reserved for your traffic, with limits set for your deployment, or the models on your own hardware for qualifying deployments. The same API, the same answers.

### Fine-tuning

- [Fine-tuning](https://decisionnode.com/docs/fine-tuning): Fine-tuning trains your own version of DecisionNode MoE or DecisionNode Flash on decisions you have labelled. It ships only when it beats the base on records it never saw, and you call it by name through the same API: decisionnode-1.0@acme/fraud.
- [Prepare a fine-tuning dataset](https://decisionnode.com/docs/fine-tuning/dataset): A dataset is a JSON Lines file of 200 to 50,000 records, up to 64 MiB. Each record is a request exactly as /v1/decide takes it, plus answers: the answer your policy gives to each question.
- [Upload and validate a dataset](https://decisionnode.com/docs/fine-tuning/upload): Create a fine-tuned model in the console, upload a dataset of up to 64 MiB, and let validation check every record: the format, the images, duplicates, conflicts and the splits. Nothing is trained or charged until the dataset is ready.
- [Start a training run](https://decisionnode.com/docs/fine-tuning/train): A run trains a new version of your model on a ready dataset. The console shows the estimate first: the expected time and the fee, 3 × the compute time + $50. Nothing is charged until the run ends, and a run that fails costs nothing.
- [Watch a training run](https://decisionnode.com/docs/fine-tuning/watch): A run moves from queued through training and evaluating to ready, no_gain, failed or cancelled. While it trains, the console shows its progress every 10 seconds: the step, the epoch, the training loss and the evaluation so far. You can cancel it at any point before it ends.
- [The fine-tuning quality gate](https://decisionnode.com/docs/fine-tuning/gate): A fine-tuned version ships only when it helps. Four tests compare it with its base: held-out accuracy at least 0.02 better and clear of chance, calibration no more than 0.01 worse, our standard test sets no more than 0.01 lower, and the same refusals. Pass all four and it is ready; miss one and it is no_gain, which costs $50.
- [Use your fine-tuned model](https://decisionnode.com/docs/fine-tuning/use): Deploy a ready version in the console, then send its name as model on /v1/decide: decisionnode-1.0@acme/fraud for the version deployed most recently, decisionnode-1.0@acme/fraud:3 for one version. The response's model always names the version that answered.
- [Fine-tuning limits and pricing](https://decisionnode.com/docs/fine-tuning/pricing): A training run costs 3 × its compute time + $50, charged when it ends: $50 only when the gate says no_gain, the compute so far when you cancel, nothing when it fails. A fine-tuned model's requests cost the base's price + $0.02 per million input tokens. No storage fee.

### Patterns

- [Confidence-gated routing](https://decisionnode.com/docs/patterns/confidence-gated-routing): Set a threshold once: every answer above it is acted on instantly, and everything below it is re-checked by the full model or takes the safe path. Calibrated confidence makes the split predictable once you have measured it on your own data.
- [Fan-out](https://decisionnode.com/docs/patterns/fan-out): Ask many questions about one input in one request, and run many inputs in parallel within your rate limits.
- [Guardrails](https://decisionnode.com/docs/patterns/guardrails): Gate an agent's tool calls: before the agent acts, ask DecisionNode whether the action is safe and in scope, and run it only above your bar.
- [Control loops](https://decisionnode.com/docs/patterns/control-loops): More than 10 decisions a second? Use a session. DecisionNode becomes the decision layer of a monitoring loop, a simulator or a drone's mission supervisor: it answers which mode or which action, and your own controller stays in charge of carrying it out.
- [Batch jobs](https://decisionnode.com/docs/patterns/batch-jobs): Send up to 10,000 requests in one file and collect the answers later, at a lower price than live calls. Every line is a normal /v1/decide request and gets the answer the live call would give. Results come with a multi-hour delay. There is no set time at which a batch runs or finishes, so poll for it.
- [Keys on devices](https://decisionnode.com/docs/patterns/device-keys): Give every device its own Decisions-only key from your provisioning server, with its own limits, spend cap and expiry, and revoke one device or a whole group by label.
- [Bill your customers per device](https://decisionnode.com/docs/patterns/bill-per-device): Your customers' devices call DecisionNode with keys of their own. Label each key with its customer, read every key's usage for the month in one call, and turn the rows into invoice lines.
- [Publishable keys](https://decisionnode.com/docs/patterns/publishable-keys): A key made to be seen, for browsers and mobile apps: decisions only, no face search, always rate-limited and capped, and limited to the origins and models you allow.

### Integrations

- [Home Assistant](https://decisionnode.com/docs/integrations/home-assistant): Ask DecisionNode about your cameras' pictures, an image or any state from Home Assistant: a decide action, standing questions as sensors, and a Frigate trigger.
- [MQTT bridge](https://decisionnode.com/docs/integrations/mqtt): Let any MQTT device ask DecisionNode questions without an SDK: it publishes a request on a topic, and the bridge publishes the answer on a response topic.
- [ROS 2](https://decisionnode.com/docs/integrations/ros2): A ROS 2 node that asks your questions about an image topic at a rate you set and publishes each set of typed answers. Decisions only, never the sole means of control.

### API reference

- [API reference](https://decisionnode.com/docs/api): One HTTPS API on our own inference stack: ask typed questions, stream decisions over a session, run batch jobs at a lower price than live calls and list the models your key can use. Base URL, keys, conventions and every endpoint, on one page.
- [POST /v1/decide](https://decisionnode.com/docs/api/decide): Answer typed questions about a state, optional images and video frames. One request, one buffered JSON response, one answer per question.
- [GET /v1/models](https://decisionnode.com/docs/api/models): List the model names your key can send, each with the pinned version it answers from today and its limits.
- [POST /v1/uploads](https://decisionnode.com/docs/api/uploads): Put an image into your workspace's storage once, then name it by upload_id in any image slot for an hour: on /v1/decide, in a batch line, in a session frame or a fine-tuning record. Up to 16 images a call; free.
- [Keys](https://decisionnode.com/docs/api/keys): Make, list, change and revoke Decisions-only keys for your devices from your provisioning server, with a Manage device keys key.
- [Key usage](https://decisionnode.com/docs/api/keys/usage): One key's usage and cost over a period: requests, tokens, booster calls and what you were charged, as totals or by hour, day or month.
- [Usage by key](https://decisionnode.com/docs/api/usage): The usage and cost of many keys over a period, one row per key, filtered by label, device or key: the read behind a monthly invoice run.
- [Errors](https://decisionnode.com/docs/api/errors): Every error is a status code plus a JSON body with a detail field. A request succeeds for every question or fails as a whole. Retry 408, 429, 529 and any 5xx; retry 402 once you have added credit; fix the request for the other 4xx. Batch jobs and sessions use the same bodies.
- [Safety check](https://decisionnode.com/docs/api/safety-check): The hosted API checks every request in the same pass as its answers. It flags requests that ask to choose or target people to be harmed, or to help someone hurt themselves. By default it only flags, with the scores in a header; stricter blocking is set per customer.
- [Rate limits](https://decisionnode.com/docs/api/rate-limits): Rate limits are your workspace's, shared by all its keys, counted in requests and input tokens a second. A key may carry its own lower limits. Over a limit, the API answers 429 with Retry-After.

### Sessions API

- [Sessions](https://decisionnode.com/docs/api/sessions): Streaming decisions. Open a session once with the fixed part of your request, then stream frames over a WebSocket and get a typed decision for each one. More than 10 decisions a second? Use a session.
- [Open a session](https://decisionnode.com/docs/api/sessions/open): Send the fixed part of your request once: model, instructions, state, questions and window. Get back a session id, the WebSocket to stream frames to, and when the session expires.
- [Stream frames](https://decisionnode.com/docs/api/sessions/stream): Connect to the session's WebSocket, send one frame per message and read one typed reply per answered frame. The socket stays open until you close it, end the session, or it expires.
- [End a session](https://decisionnode.com/docs/api/sessions/end): End a session before it expires. Its context is freed at once, an open socket closes with 1000, and nothing more is billed.

### Collections API

- [Collections API](https://decisionnode.com/docs/api/collections): Create face collections, enroll faces, list, edit and delete them. Every route takes a Full access key and acts for its workspace only.
- [Create a collection](https://decisionnode.com/docs/api/collections/create): Create a face collection for your workspace. It starts empty; enroll faces into it.
- [List collections](https://decisionnode.com/docs/api/collections/list): Your workspace's collections, newest first, then the public ones it may search.
- [Retrieve a collection](https://decisionnode.com/docs/api/collections/retrieve): One collection: yours by its id, or a public one by its name.
- [Delete a collection](https://decisionnode.com/docs/api/collections/delete): Delete one of your collections and every item in it, at once. It cannot be undone.
- [Enroll a face](https://decisionnode.com/docs/api/collections/enroll): Enroll one face from one picture into your collection, with your reference, an optional label and metadata. The picture is never kept.
- [List items](https://decisionnode.com/docs/api/collections/list-items): A page of your collection's items: all of them newest first, or those of one reference or reference prefix in reference order.
- [Update an item](https://decisionnode.com/docs/api/collections/update-item): Change an item's reference, its label or its metadata, without enrolling it again. Never billed.
- [Delete an item](https://decisionnode.com/docs/api/collections/delete-item): Delete one item of your collection, at once. It cannot be undone.
- [Add a document](https://decisionnode.com/docs/api/collections/add-document): Add a document to a knowledge base: Markdown or plain text, indexed in the background. Answers at once, or once the document is ready.
- [Replace a document](https://decisionnode.com/docs/api/collections/replace-document): Replace a document whole. A new text or title is indexed again while the old version keeps answering requests; the same text again changes nothing.
- [Retrieve an item](https://decisionnode.com/docs/api/collections/retrieve-item): One item of a collection: a face item, or a document of a knowledge base with its status and, with ?include=text, its stored text.
- [List a document's passages](https://decisionnode.com/docs/api/collections/list-chunks): The passages a document was cut into, with their headings, byte offsets, tokens and text: what a request can read from it.
- [Delete failed documents](https://decisionnode.com/docs/api/collections/delete-failed): Delete every failed document of a knowledge base in one call: the documents whose processing failed and that never got ready.
- [Search a knowledge base](https://decisionnode.com/docs/api/collections/search): Run a knowledge base's retrieval without a decision: the passages a request with this query would read, with their text. Billed as one knowledge call.

### Batch API

- [The batch object](https://decisionnode.com/docs/api/batches): A batch holds up to 10,000 /v1/decide requests that run when there is room, at a lower price than live calls. This page defines the object every batch endpoint returns, its states, its counters and its limits.
- [Create a batch](https://decisionnode.com/docs/api/batches/create): Upload requests as JSON Lines or a JSON array and get a batch in state draft. Nothing runs until you finalize it.
- [Add requests](https://decisionnode.com/docs/api/batches/add-requests): Add requests to a batch in state draft, up to 10 MiB a call. Call it as often as you need, then finalize.
- [Finalize a batch](https://decisionnode.com/docs/api/batches/finalize): Lock a draft and queue it to run. Nothing runs before this call, and from it the expiry window counts.
- [Retrieve a batch](https://decisionnode.com/docs/api/batches/retrieve): Get a batch's state, counters and timestamps. Poll it until the batch has ended, then download the results.
- [Get batch results](https://decisionnode.com/docs/api/batches/results): Download one result line per request once a batch has ended: the live status, body and headers of each. JSON Lines by default, or pages of up to 1,000 lines as JSON.
- [Cancel a batch](https://decisionnode.com/docs/api/batches/cancel): Stop a batch. Requests that have not started are cancelled and never billed; requests already running finish and are billed.
- [List batches](https://decisionnode.com/docs/api/batches/list): List the batches your key created, newest first, a page at a time.

### Pricing and billing

- [Pricing and billing](https://decisionnode.com/docs/pricing): You pay for input tokens only. Output is free because the model generates no text. The prices: DecisionNode MoE $0.042 and DecisionNode Flash $0.035 per million input tokens, from a prepaid balance. Batch jobs are 30% off the live price on DecisionNode MoE and 50% off on DecisionNode Flash. Boosters are priced per picture they read, and fine-tuning 3 × the compute time + $50 a run.
- [Refer & earn](https://decisionnode.com/docs/refer-and-earn): Share your referral link or code. A developer you refer gets $5 off their first top-up of $10 or more, and after 25 qualified referrals you earn 12% in cash of each referred workspace's usage during its first 6 months.

### Policies

- [Responsible use](https://decisionnode.com/docs/responsible-use): Most decisions can run fully automatically. Decisions about people in a few areas need a qualified person to review each one, a safety check flags requests that seek to harm people or help to self-harm (stricter blocking is set per customer), and military use needs a signed addendum. This page says what that means for your code.
- [Data and privacy](https://decisionnode.com/docs/data-and-privacy): What happens to the requests you send: how long they are kept, how to ask for zero retention, how your requests improve the models unless you opt out, and what sessions, batch jobs and the safety check hold.

## Other pages

- [Home](https://decisionnode.com): what DecisionNode is and the pricing.
- [Benchmarks](https://decisionnode.com/benchmarks): accuracy, calibration and latency against named alternatives.
- [Examples](https://decisionnode.com/examples): worked integrations.
- [Playground](https://decisionnode.com/playground): the API's request shapes, runnable with a free account.
- [Legal](https://decisionnode.com/legal)
- [Terms](https://decisionnode.com/legal/terms)
- [Acceptable use](https://decisionnode.com/legal/acceptable-use)
- [Privacy](https://decisionnode.com/legal/privacy)
- [Data processing](https://decisionnode.com/legal/data-processing)
- [Defence addendum](https://decisionnode.com/legal/defence-addendum)
- [Cookies](https://decisionnode.com/legal/cookies)
- [Affiliate program agreement](https://decisionnode.com/legal/affiliate-program-agreement)

## Full text

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