state
“Customer: I was charged twice and nobody has replied for 3 days.”
questions
- routechoice
- urgencyscore
- refundtruth
POST /v1/decide3 questions, 1 call
- route0.87
- urgency2.31
- refund0.94
- one pass
- no text generated
- our own GPUs
- input
- 62 tokens
- output
- 0, free
answers
- route"billing"
- urgency2.31
- refund0.94true
your code acts
- if refund >= 0.8issue_refund()
- elif refund >= 0.4recheck()
- elseassign(route)
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.
{
"model": "decisionnode-flash",
"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?"
}
}
}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 Flash, our fastest tier. A refund in the unsure middle (0.40 to 0.80) is re-checked by the full model, decisionnode, as the diagram shows; everything else is settled by the first answer.
Six 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), point (a spot in your image), box (a rectangle around the thing).
| Type | In the API | What it asks | What comes back |
|---|---|---|---|
| Choice | "type": "choice" | Pick one option from the list you give | choice (always one of your keys), probabilities per option, confidence |
| Score | "type": "score" | Place the input on your ordered scale | score (expected level), probabilities per level, legend, confidence |
| Truth | "type": "truth" | Is this statement true? | truth, one number from 0.00 to 1.00: the probability that the statement is true |
| Number | "type": "number" | How many, or what value? | number (a value on your grid), expected, confidence, probabilities per value |
| Point | "type": "point" | Where is it? | x, y (one spot in the image), present, confidence |
| Box | "type": "box" | Where is it, and how far does it reach? | x1, y1, x2, y2 (a rectangle around the thing), present, confidence |
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.
Images and video. Send up to 16 images in a request, as base64 or by https URL, and ask about all of them at once: a camera frame, a receipt, a parcel at the sorter. For video, send the frames from a camera with their timestamps and the model reads them as one video, with order and timing. See Images and Video.
Answers that say where. 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. Pick the next package on a belt, box the scratch on a panel, find the landing marker. See Points and boxes.
Streaming decisions. More than 10 decisions a second, for a monitoring loop, a simulator or a live camera feed? Open a session: send the context once, stream frames over a WebSocket and get a typed decision for each. Control loops shows where it fits.
Batch jobs. A backlog to route, an archive to re-score? Upload up to 10,000 requests as one batch job at a lower price per input token than live calls, and collect the same answers later. Results come with a multi-hour delay.
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 its answers can vary between calls. 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 on the data we measure; check it on yours. See Confidence.
- Deterministic. The same request to the same model version returns the same answer. There is no sampling. See Determinism.
- State read once. The state and images are encoded once and shared by every question, so ten questions cost little more than one.
A System One model#
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 one: it does not reason in text or plan a path to an answer. It reads the state once and returns, for every question, a calibrated probability over the options you allowed, in one forward pass. That makes it the right tool where the options are known in advance and the call is made thousands of times a minute: routing, triage, moderation, scoring and gating. It is not a general assistant: it writes nothing, and a question it was not asked goes unanswered.
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 Flash answers a short /v1/decide request in milliseconds: fast enough to sit inside every request and every payment. For a loop that decides many times a second, such as monitoring a camera feed, a session keeps the context loaded and answers frame after frame.
| Model | Family id you send as model | Price per 1M input tokens | Output |
|---|---|---|---|
| DecisionNode | decisionnode | $0.042 | Free |
| DecisionNode Flash | decisionnode-flash | $0.035 | Free |
On your own hardware. DecisionNode Edge and DecisionNode Edge Mini are open-weight System One decision models you download from Hugging Face and run on your own GPUs, Macs, CPUs and embedded devices, with the same request and answers. In the setup we recommend, they answer on the device and only the questions they are unsure of go on to DecisionNode Flash. Free to download under AGPL-3.0.
Choose how to call DecisionNode#
DecisionNode is one HTTPS endpoint, so any language can call it. Each way below sends the same request, one Truth question about one message, from your server, with the key read from DECISIONNODE_API_KEY.
HTTP#
Post JSON to https://api.decisionnode.com/v1/decidehttps://api.decisionnode.com/ with the key as a bearer token, from curl or any HTTP client. The Quickstart walks through a request and its answers.
curl https://api.decisionnode.com/v1/decide \
-H "Authorization: Bearer $DECISIONNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Refund me now or I cancel.",
"questions": {
"check": {
"type": "truth",
"instructions": "Is the customer asking for a refund?"
}
}
}'An SDK#
Official libraries for Python, TypeScript and JavaScript, Go, Java and Kotlin, C# and .NET, PHP, Ruby and Rust, with typed questions and answers, retries and timeouts built in. Each tab starts with its install line; each library's README has the rest.
# pip install bynn-decisionnode
from decisionnode import DecisionNode
dn = DecisionNode() # reads DECISIONNODE_API_KEY
answer = dn.check("Refund me now or I cancel.", "Is the customer asking for a refund?")
print(answer.truth) # 0.97| Language | Package | Needs at least |
|---|---|---|
| Python | bynn-decisionnode on PyPI | Python 3.10 |
| TypeScript and JavaScript | @decisionnode/sdk on npm | Node.js 20.16, Deno, Bun or an edge runtime |
| Go | github.com/ on the Go module proxy | Go 1.22 |
| Java and Kotlin | com.bynn:decisionnode on Maven Central | Java 17 |
| C# and .NET | Bynn.DecisionNode on NuGet | .NET 8 |
| PHP | bynn/decisionnode on Packagist | PHP 8.2 |
| Ruby | bynn-decisionnode on RubyGems | Ruby 3.2 |
| Rust | bynn-decisionnode on crates.io |
An MCP server for your agents#
The DecisionNode MCP server gives an agent the API's questions as tools: truth, choice, score, number, point, box, decide, decide_many and decide_video, each call a request made with your own key. It runs on your machine with uv, and your MCP client starts it. It is not the docs MCP server, which reads these pages.
uvx bynn-decisionnode-mcpThe command line#
dn asks a typed question from your terminal or a script, and prints the answer as JSON in a pipe. Homebrew, Scoop and the release archives are on its page.
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/Bynn-Intelligence/decision-node-cli/main/install.sh | sh
dn auth login
dn truth "Is the customer asking for a refund?" -s "Refund me now or I cancel."An integration#
- Home Assistant: questions about your cameras in automations, sensors and Frigate events.
- MQTT bridge: decisions for any device that can publish to an MQTT broker.
- ROS 2: a node that asks your questions about an image topic and publishes the answers.
A coding agent#
Paste this line into the agent that works in your repository and tell it what to decide. It fetches the setup guide and writes the integration with the SDK for your language. See With coding agents.
Set up DecisionNode for me: fetch and follow this guide https://decisionnode.com/agent-setup.mdStart here#
- Quickstart5 minGet a key, send one request, branch on the answer. Under five minutes.Read
- With coding agentsagentsA prompt to paste into your coding agent and a decide tool for your own agents.Read
- ExamplesrecipesComplete recipes: traffic and people counts, incidents, the sorting line, support triage, moderation, receipts.Read
- POST /v1/decidereferenceEvery field of the request and the response, headers and errors.Read