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

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.

on this page9 sections
  1. What it answers
  2. Request
  3. Response
  4. On text
  5. On an image
  6. The grid
  7. Reading the answer
  8. Beyond counting
  9. Billing
Number“How many invoices on this statement are overdue on the statement date?”

4(0.00)

the most probable value on a grid of 0 to 30with the probability of every value

  1. 0.84
0430
  • 2 0.01
  • 3 0.07
  • 4 0.84
  • 5 0.07
  • 6 0.01

number 4expected 4.00confidence 0.84your code sends the reminder for 4

A number question asks for one value on a grid you set. Above, a customer statement goes in as text and overdue comes back as 4 with probability 0.84, the full distribution over 0 to 30 below it. It is the fourth type, next to Choice, Score and Truth, and it is read the same way: a typed answer with probabilities you can threshold.

Any grid you set

Whole numbers, halves ("step": 0.5) or one decimal ("step": 0.1), on any range. A grid of up to 256 values is one question; a finer or wider one, up to 4,096 values, is composed inside the same call, and you still get one answer. See The grid.

What it answers#

  • Counts: cars in a drone frame, items on a shelf, pallets in a bay, overdue invoices in a statement, open findings in a report, steps in a plan another model wrote.
  • Values read off the input: the year a contract was signed, the days until a deadline, the percentage of a page that is tables, a price in a stated range.
  • Ratings and brackets: a review's rating out of ten in halves, an age bracket from a form, a severity from 1 to 5 when the levels are plain numbers.

Use a Score when each level has a meaning in words (routine, urgent, critical). Use a number when the answer is a quantity, and the values in between mean what they say.

Request#

JSON
{
  "cars": {
    "type": "number",
    "instructions": "How many cars are visible in the image?",
    "min": 0,
    "max": 50
  }
}
type"number"required
The question type.
instructionsstring
What to count or read, in one sentence. The same field as on every type.
minnumberdefault 0
The lowest value the answer can take.
maxnumberdefault 255
The highest value, at least min.
stepnumberdefault 1
The spacing of the grid, above 0: 1 for whole numbers, 0.5 for halves, 0.1 for one decimal. The grid runs from min in steps of step up to the last value at or below max.

A number question uses no criteria: the grid is the set of answers. A min, max or step that is not a number, min above max, a step of 0 or below, a min or step with more than 6 decimals, or a grid of more than 4,096 values is refused with a 422 whose detail list names the field (min, max, step or the grid), and nothing is charged. See Errors.

Response#

JSON
{
  "cars": {
    "type": "number",
    "number": 7,
    "expected": 7.0,
    "confidence": 0.78,
    "probabilities": { "5": 0.01, "6": 0.1, "7": 0.78, "8": 0.1, "9": 0.01 }
  }
}
numbernumber
The most probable value of the grid. Always a value your grid allows, written as the grid writes it: 7 on a whole-number grid, 3.5 on a grid of 0.5. Read it as a float in a typed client.
expectednumber
The probability-weighted mean: a fractional estimate, even on a whole-number grid. A float rounded to 2 decimals, so a whole value prints with its decimal point (7.0).
confidencenumber
The probability of number, from 0 to 1.
probabilitiesobject
Every grid value whose probability is above 0.001, keyed by the value as a string ("7", "3.5"), each to 3 decimals: an exception to the 2-decimal rule of other answers. The list is sparse and is not corrected toward a sum of 1, so the listed values sum to at most 1, and less over a wide grid.

expected = sum(v · p_v)

confidence = p_number

v
a value of the grid
p_v
the probability of v
p_number
the probability of the most probable value

Keys are written the shortest way: "7", never "7.0"; "3.5", never "3.50". Parse them as numbers before you sort: in most languages an object keeps "10" ahead of "2.5".

On text#

A statement as an accounting system exports it, with two number questions and a Choice in one request. overdue counts the invoices past due on the statement date (4); oldest_days reads how late the oldest one is (78, expected 78.08); reminder picks what to send. Every answer comes from one read of the statement.

POSThttps://api.decisionnode.com/v1/decide
Open playground
statement.txt
Customer statement
Account: Norrvik Supply AB (30-4471)
Statement date: 2026-10-01
Terms: net 30, amounts in EUR

Invoice   Issued      Due         Amount    Status
INV-2041  2026-06-15  2026-07-15  1,240.00  open
INV-2058  2026-07-03  2026-08-02    410.00  paid 2026-08-01
INV-2063  2026-07-21  2026-08-20    860.00  open
INV-2069  2026-07-29  2026-08-28    395.00  paid 2026-09-02
INV-2077  2026-08-06  2026-09-05  1,120.00  part paid, 300.00 open
INV-2081  2026-08-13  2026-09-12    640.00  open
INV-2090  2026-08-31  2026-09-30    780.00  paid 2026-09-29
INV-2094  2026-09-10  2026-10-10    520.00  open
INV-2102  2026-09-24  2026-10-24    915.00  open

The request carries that statement as its state, one JSON string. Below it reads as a placeholder so the questions stay in view; the copy button copies the full request, statement included, ready to run.

curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode",
    "state": "<statement.txt, above>",
    "questions": {
      "overdue": {
        "type": "number",
        "instructions": "How many invoices on this statement are overdue on the statement date?",
        "min": 0,
        "max": 30
      },
      "oldest_days": {
        "type": "number",
        "instructions": "How many days past its due date is the oldest unpaid invoice?",
        "min": 0,
        "max": 180
      },
      "reminder": {
        "type": "choice",
        "instructions": "Which reminder should go out today?",
        "criteria": {
          "none": "nothing is overdue, send nothing",
          "friendly": "a friendly reminder for one recent invoice",
          "firm": "a firm reminder listing every overdue invoice",
          "final": "a final notice before the account is passed to collections"
        }
      }
    }
  }'
200 OK
{
  "model": "decisionnode-main-0.9.1-rc1",
  "answers": {
    "overdue": {
      "type": "number",
      "number": 4,
      "expected": 4.0,
      "confidence": 0.84,
      "probabilities": {
        "2": 0.01,
        "3": 0.07,
        "4": 0.84,
        "5": 0.07,
        "6": 0.01
      }
    },
    "oldest_days": {
      "type": "number",
      "number": 78,
      "expected": 78.08,
      "confidence": 0.61,
      "probabilities": {
        "75": 0.01,
        "76": 0.03,
        "77": 0.13,
        "78": 0.61,
        "79": 0.14,
        "80": 0.05,
        "81": 0.02,
        "82": 0.01
      }
    },
    "reminder": {
      "type": "choice",
      "choice": "firm",
      "confidence": 0.68,
      "probabilities": {
        "final": 0.19,
        "firm": 0.76,
        "friendly": 0.04,
        "none": 0.01
      }
    }
  },
  "usage": {
    "input_tokens": 445,
    "output_tokens": 0,
    "cost": {
      "usd": 0.00001869,
      "model_usd": 0.00001869,
      "boosters_usd": 0,
      "free_tier": false
    }
  }
}

On an image#

images[0] "frame"cars 7 (0.78)

Drone photo looking straight down on a parking row of ten marked bays: seven cars parked (white, black, silver, navy, red, graphite and champagne) and three empty bays, with a pavement, a lamp post and a grass verge below.

one read of the frame: the answer is the count and its distribution, not where each object is

state

Drone frame over row B4 of the north car park, camera pointing straight down.

question

cars How many cars are visible in the image?

input 328 tokensoutput 0, free

carsNumberexpected 7.00

7(0.00)

  1. 0.78
0750
  • 5 0.01
  • 6 0.10
  • 7 0.78
  • 8 0.10
  • 9 0.01

your code logs 7 cars at confidence 0.70 or more

How many cars are visible in the image? 7, probability 0.78, expected value 7.00.

The frame goes in images, the question asks for a count on a 0 to 50 grid, and the answer is a number your code can store, compare or act on. DecisionNode reads the image itself, in the same pass as the state and the question: there is no caption step in between.

On video frames

Number questions work on text, on images and on video frames sent with their timestamps. On a video the count can run over time: how many forklifts pass the door, how many people enter in ten seconds.

POSThttps://api.decisionnode.com/v1/decide
Open playground
curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode",
    "state": "Drone frame over row B4 of the north car park, camera pointing straight down.",
    "images": [
      { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
    ],
    "questions": {
      "cars": {
        "type": "number",
        "instructions": "How many cars are visible in the image?",
        "min": 0,
        "max": 50
      }
    }
  }'

Give small objects the pixels they need

Count where every object is clearly visible. Many small objects need a sharper image, within the image limits on Limits (up to 10 MB each). Crop to the area that matters rather than sending the whole scene.

The grid#

min, max and step set every value the answer can take. Without them the grid is 0 to 255 in whole numbers. A grid of up to 256 values is answered as one question. A finer or wider grid is composed inside the same call, and you still get one answer. A grid holds at most 4,096 values in all: 0 to 1000 at step 0.1 (10,001 values) is refused with 422, so narrow the range or widen the step.

  • Cars in a frame

    Request
    "min": 0, "max": 50
    Values
    51
    Answered as
    One question
  • Year a contract was signed

    Request
    "min": 1990, "max": 2026
    Values
    37
    Answered as
    One question
  • Default range

    Request
    no min, max or step
    Values
    256
    Answered as
    One question
  • Rating in halves

    Request
    "min": 0, "max": 5, "step": 0.5
    Values
    11
    Answered as
    One question
  • Percentage, one decimal

    Request
    "min": 0, "max": 100, "step": 0.1
    Values
    1,001
    Answered as
    Composed in the same call
  • Price in a stated range

    Request
    "min": 0, "max": 2000, "step": 5
    Values
    401
    Answered as
    Composed in the same call
Grids and what they ask for
GridRequestValuesAnswered as
Cars in a frame"min": 0, "max": 5051One question
Year a contract was signed"min": 1990, "max": 202637One question
Default rangeno min, max or step256One question
Rating in halves"min": 0, "max": 5, "step": 0.511One question
Percentage, one decimal"min": 0, "max": 100, "step": 0.11,001Composed in the same call
Price in a stated range"min": 0, "max": 2000, "step": 5401Composed in the same call

A composed grid answers like any other: number is a value of your grid, expected and confidence mean the same, and probabilities lists every grid value above 0.001, to 3 decimals. Keys follow your step: "42.5" on a grid of 0.1, "1995" on a grid of 5. A tight range is still worth setting: the fewer values, the less a question costs and the sharper the distribution. See Errors for a grid that cannot be built.

Reading the answer#

  • Act on number when confidence clears the bar you set for this question. The frame above, 7 at 0.78, is a count your code can log, bill or route on.
  • Use expected where a fractional estimate is better than a whole one: averages across many frames, forecasts, sorting.
  • Read probabilities for the shape. A split answer, "probably 7, maybe 8", looks like {"6": 0.21, "7": 0.62, "8": 0.14}: number is 7 at 0.62, and adding its neighbours gives 0.97, the chance the true value is within one.

"Probably 7, maybe 8" never waits on anyone. Below your bar, your code escalates on its own: it re-checks with DecisionNode when the first call went to DecisionNode Flash, and if the answer is still split it takes the safe end of what is likely, such as planning for 8 cars rather than 7.

# decide(request) posts the request to /v1/decide and returns its answers
ACT_AT = 0.7   # per question, in config

def count_cars(request):
    cars = decide({**request, "model": "decisionnode-flash"})["cars"]
    if cars["confidence"] < ACT_AT:     # probably 7, maybe 8: ask the full model
        cars = decide({**request, "model": "decisionnode"})["cars"]
    if cars["confidence"] >= ACT_AT:
        return cars["number"]           # sure: act on it

    # still split: take the high end of the likely values, automatically
    likely = [float(v) for v, p in cars["probabilities"].items() if p >= 0.1]
    # nothing reaches 0.1 (a wide, flat spread): the most probable value
    return int(max(likely, default=cars["number"]))  # a whole-number grid: an int

Beyond counting#

  • Traffic and areas: cars passing a junction, people in a square, vehicles in a yard, from a camera frame or from video frames.
  • Retail and logistics: items on a shelf, pallets in a bay, products on a line, from one camera frame.
  • Documents: overdue invoices in a statement, open findings in an audit report, mentions of a product in a thread.
  • Agriculture and inspection: fruit on a branch, defects on a surface, animals in a pen.
  • Checks on other models: how many steps a generated plan has, how many sources an answer cites.
  • Values, not counts: the year a document was issued, a percentage to one decimal, a price in a stated range, a rating in halves.

Billing#

A number question is billed like a choice with one option per grid value: a 0 to 50 count like a choice of 51 options. A grid of more than 256 values is composed in the same call: it is cut into the fewest equal pages of at most 256 values (300 values make two pages of 150), one choice picks the page and one choice per page picks the value within it. It is billed for every question it is composed of, the page choice and every page, so a wider or finer grid costs more: set the tightest range you can. The response's usage.input_tokens is always the exact figure. Image tokens are priced as on every call, and batch jobs take number questions at their lower price, like every other type. Output stays free. See Pricing and billing.

previousTruthnextPoints and boxes

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 it answers
  2. Request
  3. Response
  4. On text
  5. On an image
  6. The grid
  7. Reading the answer
  8. Beyond counting
  9. Billing