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

on this page4 sections
  1. Request
  2. Response
  3. Formulas
  4. Using a score
Score“How urgent is this?”
  1. 0.01
  2. 0.09
  3. 0.48
  4. 0.42
  1. 0 routine
  2. 1 today
  3. 2 urgent
  4. 3 critical

score 2.31 of 3confidence 0.47

Request#

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

criteria is an array of levels from lowest to highest, up to 10 of them (two or more make a scale). Level indexes start at 0 in the order you send them. A level is a string, an object (for example what with examples) or an array; a null level is a 422. With a single level the answer is that level at probability 1, score 0.0 and confidence 1.0.

JSON
{
  "severity": {
    "type": "score",
    "instructions": "How severe is this bug report?",
    "criteria": [
      "cosmetic",
      {
        "what": "a feature works badly",
        "examples": ["slow search", "wrong sort order"]
      },
      {
        "what": "a feature does not work",
        "examples": ["checkout fails"]
      }
    ]
  }
}

Response#

JSON
{
  "urgency": {
    "type": "score",
    "score": 2.31,
    "confidence": 0.47,
    "legend": {
      "0": "routine",
      "1": "today",
      "2": "urgent",
      "3": "critical"
    },
    "probabilities": { "0": 0.01, "1": 0.09, "2": 0.48, "3": 0.42 }
  }
}
scorenumber
The expected level index: the sum of each index times its probability.
probabilitiesobject
Level index (a string, "0" upward) to probability, one entry per level, in level order. They sum to 1, up to rounding.
legendobject
Level index to your level, exactly as sent: a level sent as an object or an array comes back as that object or array, not as text.
confidencenumber
How tightly the probability sits around the most likely level, from 0 to 1.

Formulas#

score = sum(i · p_i)

confidence = 1 − E[|i − m|] / D(K)

D(K) = floor(K · K / 4) / K

i
the level index, from 0
p_i
the probability of level i
K
the number of levels
m
the most likely level, the lowest one on a tie
E[|i − m|]
the expected distance from m: sum(p_i · |i − m|)
D(K)
the largest that distance can be on K levels

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

Worked example

score = 0 · 0.01 + 1 · 0.09

+ 2 · 0.48 + 3 · 0.42 = 2.31

m = 2 (urgent)

E = 0.01 · 2 + 0.09 · 1

+ 0.48 · 0 + 0.42 · 1 = 0.53

D(4) = floor(4 · 4 / 4) / 4 = 1

confidence = 1 − 0.53 / 1 = 0.47

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

Using a score#

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

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. Request
  2. Response
  3. Formulas
  4. Using a score