- Base URL
https://api.decisionnode.comhttps://api.decisionnode.com- Authentication
Authorization: Bearer dn_live_...on every call; keys are created in the console- Format
- JSON request and response bodies; JSON Lines for batch uploads and results
- Models
decisionnodeanddecisionnode-flash, a pinned version such asdecisionnode-main-0.9.1-rc1, or your own fine-tuned model such asdecisionnode-flash@acme/fraud - Errors
- A status code and a
detailbody; see Errors - Request id
x-request-idon every response; log it with the status- Safety
- Every decision response carries
x-decisionnode-safety; see Safety check - Boosters
- Up to 4 specialist readings of a request's images, returned in
evidence; see Boosters - Rate limits
- Per workspace, shared by its keys, counted per second; see Rate limits
Endpoints#
| Endpoint | What it does |
|---|---|
POST /v1/decide | Answers typed questions about a state, images and video frames: choice, score, truth, number, point or box |
POST /v1/systemone | The same decisions in the System One request format, for clients and benchmark harnesses written for it |
GET /v1/models | Lists the models your key can send, your fine-tuned models included, with their prices, limits, upload and video limits and batch limits |
POST /v1/uploads | Puts images into your workspace's storage, to name by upload_id for an hour |
POST /v1/sessions | Opens a session: the fixed part of your request, sent once |
WS /v1/sessions/{id}/stream | Streams frames and one typed reply per answered frame |
DELETE /v1/sessions/{id} | Ends a session |
POST /v1/credit | Buys prepaid credit with a machine payment: a 402 challenge, paid with a card through a Stripe Shared Payment Token, USDC on Tempo or USDC on Base; without a key, it makes an agent workspace and a key |
POST /v1/batches | Creates a batch from a JSON Lines file or a JSON array |
POST /v1/batches/{id}/requests | Adds requests to a draft batch |
POST /v1/batches/{id}/finalize | Queues a draft to run |
GET /v1/batches/{id} | Returns a batch's state and counters |
GET /v1/batches/{id}/results | Returns one result line per request |
POST /v1/batches/{id}/cancel | Cancels what has not started |
GET /v1/batches | Lists your key's batches |
Which call to use#
| You need | Call | Billed |
|---|---|---|
| An answer now, for one input | POST /v1/decide | Input tokens at the live price |
| More than 10 answers a second about one evolving input | A session | The fixed part once, then each frame's tokens, at the live price |
| Answers for a large set nothing is waiting on | A batch job | Input tokens of completed requests at 30% off the live price on DecisionNode and 50% off on DecisionNode Flash |
All three take the same questions and return the same answers: the same request on the same model version gets the same answer, whichever way it is sent. Output is free on all three.
Authentication#
Send your key as a bearer token on every call, the session stream included. Keys start with dn_live_. A key has one of four kinds: Full access and Manage device keys keys stay on your server, in an environment variable such as DECISIONNODE_API_KEY; a device gets a Decisions-only key of its own, and only a Publishable key goes in a browser or an app. A call outside a key's kind gets 403 key_scope_denied. A missing, unknown, expired or revoked key gets 401; batches and sessions belong to the key that created them.
Conventions#
- JSON. Bodies are UTF-8 JSON; batch uploads may be JSON Lines, one request per line.
- Names. Fields are
snake_case. Your question keys and batchcustom_ids come back exactly as you sent them. - Numbers. Probabilities, confidences, scores and truths are rounded to 2 decimals. One exception: a number answer's
probabilitiesare listed to 3 decimals. - Times. Timestamps are ISO 8601 strings in UTC, such as
2026-10-06T09:12:04Z. - Ids. Batch ids start with
batch_, session ids withses_, request ids withreq_. Treat them as opaque strings. - Paging. List endpoints take
offsetandlimitand returnnext_offset,nullon the last page. - Determinism. The same request to the same model version returns the same answer. Pin a version to keep answers fixed across releases.
Versions#
decisionnode and decisionnode-flash move to each new release. A pinned id such as decisionnode-main-0.9.1-rc1 never changes, and every response names the version that answered: model in the body, x-decisionnode-model in the headers. During a rollout, while the servers move to a new version, a request may be answered by any version a server of the family reports; the header names exactly what answered. GET /v1/models names each family's current version.
Errors and limits#
Errors share one body: detail, with an error_type and a message, or a list of fields for a 422. One rule covers every endpoint: retry 408, 429, 529 and any 5xx, waiting at least what Retry-After says when it is set, and fix the request for the other 4xx. A limit or a bad request is never reported as a 5xx, so a 5xx is always safe to retry. Errors lists every status and type, Limits every size limit, and Rate limits what counts against your key.