Skip to content
DecisionNodeDecisionNdedocs
  • Guides
  • API reference
  • Examples
  • Playground

start here

  • QuickstartGet startedGet an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state, optional images and video frames. One request, one buffered JSON response, one answer per question.
  • QuestionsConceptsQuestions 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…
  • ConfidenceConceptsProbabilities are calibrated per question type, so a threshold means what it says on the data we measure.
  • ImagesConceptsSend up to 16 images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and…
  • Batch jobsPatternsSend up to 10,000 requests in one file and collect the answers later, at a lower price than live calls.
  • Pricing and billingEvery workspace runs on a plan: Starter, Pro, Business or Dedicated.
↑↓ moveopen7 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  1. docs
  2. /
  3. Get started

Send state and questions. Get typed answers.

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.

on this page7 sections
  1. What you send and what comes back
  2. Six question types
  3. Why a decision model
  4. A System One model
  5. The model and the machine
  6. Choose how to call DecisionNode
  7. HTTP
  8. An SDK
  9. An MCP server for your agents
  10. The command line
  11. An integration
  12. A coding agent
  13. Start here
your code sends

state

“Customer: I was charged twice and nobody has replied for 3 days.”

questions

  • routechoice
  • urgencyscore
  • refundtruth

POST /v1/decide3 questions, 1 call

one request
our model, our GPUs
DecisionNode Flash5 ms server side, short request
stateread once
  • route0.87
  • urgency2.31
  • refund0.94
  • one pass
  • no text generated
  • our own GPUs
input
62 tokens
output
0, free
typed answers
your code receives

answers

  • route"billing"
  • urgency2.31
  • refund0.94true

your code acts

  • if refund >= 0.8issue_refund()
  • elif refund >= 0.4recheck()
  • elseassign(route)
One request in, typed answers out. The state is read once, every question is answered from that one reading, and the same request always gets the same answer.

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

  • Choice

    In the API
    "type": "choice"
    What it asks
    Pick one option from the list you give
    What comes back
    choice (always one of your keys), probabilities per option, confidence
  • Score

    In the API
    "type": "score"
    What it asks
    Place the input on your ordered scale
    What comes back
    score (expected level), probabilities per level, legend, confidence
  • Truth

    In the API
    "type": "truth"
    What it asks
    Is this statement true?
    What comes back
    truth, one number from 0.00 to 1.00: the probability that the statement is true
  • Number

    In the API
    "type": "number"
    What it asks
    How many, or what value?
    What comes back
    number (a value on your grid), expected, confidence, probabilities per value
  • Point

    In the API
    "type": "point"
    What it asks
    Where is it?
    What comes back
    x, y (one spot in the image), present, confidence
  • Box

    In the API
    "type": "box"
    What it asks
    Where is it, and how far does it reach?
    What comes back
    x1, y1, x2, y2 (a rectangle around the thing), present, confidence
The six question types
TypeIn the APIWhat it asksWhat comes back
Choice"type": "choice"Pick one option from the list you givechoice (always one of your keys), probabilities per option, confidence
Score"type": "score"Place the input on your ordered scalescore (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.

  • DecisionNode

    Family id you send as model
    decisionnode
    Price per 1M input tokens
    $0.042
    Output
    Free
  • DecisionNode Flash

    Family id you send as model
    decisionnode-flash
    Price per 1M input tokens
    $0.035
    Output
    Free
The two models
ModelFamily id you send as modelPrice per 1M input tokensOutput
DecisionNodedecisionnode$0.042Free
DecisionNode Flashdecisionnode-flash$0.035Free

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/v1/decide with the key as a bearer token, from curl or any HTTP client. The Quickstart walks through a request and its answers.

curl
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
  • Python

    Package
    bynn-decisionnode on PyPI
    Needs at least
    Python 3.10
  • TypeScript and JavaScript

    Package
    @decisionnode/sdk on npm
    Needs at least
    Node.js 20.16, Deno, Bun or an edge runtime
  • Go

    Package
    github.com/Bynn-Intelligence/decision-node-go on the Go module proxy
    Needs at least
    Go 1.22
  • Java and Kotlin

    Package
    com.bynn:decisionnode on Maven Central
    Needs at least
    Java 17
  • C# and .NET

    Package
    Bynn.DecisionNode on NuGet
    Needs at least
    .NET 8
  • PHP

    Package
    bynn/decisionnode on Packagist
    Needs at least
    PHP 8.2
  • Ruby

    Package
    bynn-decisionnode on RubyGems
    Needs at least
    Ruby 3.2
  • Rust

    Package
    bynn-decisionnode on crates.io
    Needs at least
The SDKs
LanguagePackageNeeds at least
Pythonbynn-decisionnode on PyPIPython 3.10
TypeScript and JavaScript@decisionnode/sdk on npmNode.js 20.16, Deno, Bun or an edge runtime
Gogithub.com/Bynn-Intelligence/decision-node-go on the Go module proxyGo 1.22
Java and Kotlincom.bynn:decisionnode on Maven CentralJava 17
C# and .NETBynn.DecisionNode on NuGet.NET 8
PHPbynn/decisionnode on PackagistPHP 8.2
Rubybynn-decisionnode on RubyGemsRuby 3.2
Rustbynn-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-mcp

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

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

Agent prompt
Set up DecisionNode for me: fetch and follow this guide https://decisionnode.com/agent-setup.md

Start 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
nextQuickstart

DecisionNode is built and run by Bynn Intelligence, Inc.

  • Home
  • Playground
  • Examples
  • Console
  • Responsible use
  • Terms
  • Acceptable use
  • Privacy
  • Data processing
  • Defence addendum
  • Cookies
  • Affiliate program

on this page

  1. What you send and what comes back
  2. Six question types
  3. Why a decision model
  4. A System One model
  5. The model and the machine
  6. Choose how to call DecisionNode
  7. HTTP
  8. An SDK
  9. An MCP server for your agents
  10. The command line
  11. An integration
  12. A coding agent
  13. Start here