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

Questions

Questions 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 Truth (the probability that a statement is true), a number on your grid, a point in your image or a box around the thing.

on this page6 sections
  1. The questions map
  2. Question fields
  3. Writing questions that work
  4. Better answers: give it the facts and the rule
  5. How to write it
  6. In the playground examples
  7. Structured instructions
  8. How questions are answered

Six 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 choice

    Goal
    Pick one option from the list you give
    What comes back
    choice (always one of your keys), probabilities per option, confidence
  • Score score

    Goal
    Place the input on your ordered scale or rubric
    What comes back
    score (expected level, for example 2.31 of 0 to 3), probabilities per level, legend, confidence
  • Truth truth

    Goal
    Is this statement true?
    What comes back
    truth, one probability from 0.00 to 1.00 that the statement is true
  • Number number

    Goal
    How many, or what value?
    What comes back
    number (a value on your grid), expected, confidence, probabilities per value
  • Point point

    Goal
    Where is it?
    What comes back
    x, y (one spot in the image), present, confidence, image, width, height
  • Box box

    Goal
    Where is it, and how far does it reach?
    What comes back
    x1, y1, x2, y2 (a rectangle around the thing), present, confidence, image, width, height
Question types
TypeGoalWhat comes back
Choice choicePick one option from the list you givechoice (always one of your keys), probabilities per option, confidence
Score scorePlace the input on your ordered scale or rubricscore (expected level, for example 2.31 of 0 to 3), probabilities per level, legend, confidence
Truth truthIs this statement true?truth, one probability from 0.00 to 1.00 that the statement is true
Number numberHow many, or what value?number (a value on your grid), expected, confidence, probabilities per value
Point pointWhere is it?x, y (one spot in the image), present, confidence, image, width, height
Box boxWhere is it, and how far does it reach?x1, y1, x2, y2 (a rectangle around the thing), present, confidence, image, width, height

Point and box answer 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. See Points and boxes.

What a Truth answer means

Is this statement true? 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.

What a Number answer means

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

The questions map#

questions is an object. Its keys are your names for the questions, and the answers come back under the same keys. Use short, stable names your code can read, such as route or refund. The keys are labels for your code: the model never sees them, so each question must carry its full meaning in its instructions and criteria.

  • Any string is a key. Spaces, punctuation, dots, numeric strings such as 01 and the empty string all work: same_as_record_18, plot_price.style? and __overall__::judge are valid keys.
  • Keys come back byte for byte. No trimming, no case folding, no reordering of characters, so Route with a trailing space is answered as Route .
  • No length limit of their own. A key is bounded only by the body size. Option names are bounded by the token limit, since the model reads them.
  • No count limit. A request may hold as many questions as its tokens allow: 300 short questions about a short state are answered in one call.
  • Order inside a question does not matter. type, instructions and criteria can come in any order.
JSON
{
  "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?"
    }
  }
}

Question fields#

type"choice" | "score" | "truth" | "number" | "point" | "box"required
Fixes the answer's shape: choice, score, truth, number, point or box. Point and box answer where in an image; see Points and boxes.
instructionsstring | object | array
What to decide, in plain words, almost always worth one sentence. A string is the usual form; an object or an array can carry the question with the data it refers to (see Structured instructions). A choice, a score and a number can leave it out and are answered from their options, levels or grid alone. A truth question needs instructions or criteria: with neither, it is refused with a 400.
criteriaobject | array
Choice: an object of option names to what each option means (1 to 255), required; an empty object is a 400. Score: an array of levels from lowest to highest (up to 10), required. Truth: optional { "true": "...", "false": "..." } describing what true and false mean. Number: not used. The pages of each type list the forms a description may take.
min, max, stepnumber
Number only: the grid of values the answer can take. Default 0 to 255, step 1; steps such as 0.5 and 0.1 work too. Up to 256 values are one question, and finer or wider grids are composed in the same call, up to 4,096 values in all. See Number.

Writing questions that work#

  • Ask one thing. "Is this urgent and about billing?" is two questions. Split it and you get two calibrated answers.
  • Describe every option. "bug": "something is broken" beats a bare key. The description is what the model compares against.
  • Cover the space. If an input can fit none of your options, add one for that, such as "other": "none of these". A choice always returns one of your keys.
  • Order scales from low to high. Score levels are indexed from 0 in the order you send them, and the expected score depends on that order.
  • Phrase a Truth question as a statement that can be true. "Does the receipt show the same total as the claim?" reads better than "check the receipt".
  • Give a number question the range it can really take. "How many cars are visible?" on 0 to 50 for a ten-bay row, not the default 0 to 255. A tight grid puts the probability where it belongs.

Better answers: give it the facts and the rule#

A question alone is a complete request: it is answered from its own words. But then the model can only guess what you mean. Put the facts in a JSON state and say in criteria what true and false mean, and the answer follows your rule instead of a guess.

Is a hot dog a sandwich?
{
  "questions": {
    "is_sandwich": {
      "type": "truth",
      "instructions": "Is hotdog a sandwich?"
    }
  }
}
  • Plain: "Is hotdog a sandwich?"

    DecisionNode Flash
    0.94
    DecisionNode
    0.52
    Input tokens
    19
  • A split bun counts

    DecisionNode Flash
    0.97
    DecisionNode
    0.83
    Input tokens
    137
  • Only two slices count

    DecisionNode Flash
    0.33
    DecisionNode
    0.02
    Input tokens
    145
Measured in production on 2026-10-13, the median of 3
RequestDecisionNode FlashDecisionNodeInput tokens
Plain: "Is hotdog a sandwich?"0.940.5219
A split bun counts0.970.83137
Only two slices count0.330.02145

Asked plain, the two models guess differently: 0.94 and 0.52. Given the facts and a rule, both follow the rule: a split bun that counts as bread makes it a sandwich, and a rule of two separate slices makes it not one. On DecisionNode Flash the stricter rule brings the answer down to 0.33, not all the way: the answer moves toward the rule you state, so state it.

  • The state carries the facts: here, what a hot dog is, so the model reads the thing you mean instead of recalling one.
  • The criteria say what true and false mean, so the answer applies your rule, not the model's idea of the word.
  • Instructions can point at a state field in backticks: "Is food a sandwich?" asks about exactly the fact in food.

How to write it#

  1. 1.Put the facts in a JSON state, as named fields.
  2. 2.Say in criteria what true and false mean, or what each option or level means.
  3. 3.Refer to state fields in backticks, such as food or claimed_total.
  4. 4.Ask one decision per question.

In the playground examples#

The same holds across the playground's examples. Each was asked plain, as a short sentence with no criteria, and with its state and criteria, on DecisionNode Flash, the model a playground run uses, the median of 3. Open one in the playground and choose Compare with a plain question under Run to see both answers side by side.

  • Name the commit

    Question
    kind
    Plain
    fix 0.57
    With state and criteria
    fix 0.71
  • Traffic

    Question
    queue
    Plain
    6 at 0.35
    With state and criteria
    6 at 0.63
  • Question
    congestion
    Plain
    jammed 0.63
    With state and criteria
    slow 0.43 (the intended answer)
  • Question
    wrong_way
    Plain
    0.75
    With state and criteria
    0.16 (the intended answer is no)
  • People count

    Question
    people
    Plain
    0 at 0.52
    With state and criteria
    25 at 0.14 (23 are there)
  • Question
    crowding
    Plain
    busy 0.53
    With state and criteria
    busy 0.53
  • Question
    exit_blocked
    Plain
    0.31
    With state and criteria
    0.00 (the intended answer is no)
  • Sorter

    Question
    lane
    Plain
    lane_1 0.99
    With state and criteria
    lane_2 1.00 (the intended lane)
  • Question
    damaged
    Plain
    0.17
    With state and criteria
    0.01
  • Question
    label_readable
    Plain
    0.04
    With state and criteria
    0.98
  • Agent guardrail

    Question
    verdict
    Plain
    block 0.73
    With state and criteria
    block 0.82
  • Question
    risk
    Plain
    destructive 0.79
    With state and criteria
    destructive 0.85
  • Question
    in_scope
    Plain
    0.18
    With state and criteria
    0.05
  • Receipt check

    Question
    total_matches
    Plain
    0.44
    With state and criteria
    1.00
  • Question
    date_matches
    Plain
    1.00
    With state and criteria
    1.00
  • Question
    currency
    Plain
    SEK 0.82
    With state and criteria
    SEK 1.00
  • Question
    legible
    Plain
    fully readable 0.99
    With state and criteria
    fully readable 1.00
  • Question
    alcohol
    Plain
    0.92
    With state and criteria
    0.99
  • Age gate

    Question
    adult
    Plain
    0.01
    With state and criteria
    0.00
  • Question
    matches_stated
    Plain
    0.88
    With state and criteria
    0.11 (the intended answer is no)
  • Question
    age_band
    Plain
    under_13 1.00
    With state and criteria
    under_13 1.00
Plain against state and criteria
ExampleQuestionPlainWith state and criteria
Name the commitkindfix 0.57fix 0.71
Trafficqueue6 at 0.356 at 0.63
congestionjammed 0.63slow 0.43 (the intended answer)
wrong_way0.750.16 (the intended answer is no)
People countpeople0 at 0.5225 at 0.14 (23 are there)
crowdingbusy 0.53busy 0.53
exit_blocked0.310.00 (the intended answer is no)
Sorterlanelane_1 0.99lane_2 1.00 (the intended lane)
damaged0.170.01
label_readable0.040.98
Agent guardrailverdictblock 0.73block 0.82
riskdestructive 0.79destructive 0.85
in_scope0.180.05
Receipt checktotal_matches0.441.00
date_matches1.001.00
currencySEK 0.82SEK 1.00
legiblefully readable 0.99fully readable 1.00
alcohol0.920.99
Age gateadult0.010.00
matches_stated0.880.11 (the intended answer is no)
age_bandunder_13 1.00under_13 1.00

Choice: name the commit. The criteria say what each kind of commit means, so the message is compared with a definition, not a word.

{
  "state": "Stop skipping the last page when the cursor lands on an exact multiple of the page size. Adds a regression test for 100 items at 25 per page.",
  "questions": {
    "kind": {
      "type": "choice",
      "instructions": "What kind of commit is this?",
      "criteria": {
        "feat": "",
        "fix": "",
        "refactor": "",
        "docs": "",
        "chore": ""
      }
    }
  }
}

Junction camera that times its own signals. The state says which lane is which and which way each one faces; the criteria say what facing the wrong way is.

{
  "images": [
    { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "questions": {
    "queue": {
      "type": "number",
      "instructions": "How many cars are waiting?",
      "min": 0,
      "max": 40
    },
    "congestion": {
      "type": "score",
      "instructions": "How bad is the traffic?",
      "criteria": ["free flowing", "busy", "slow", "jammed"]
    },
    "wrong_way": {
      "type": "truth",
      "instructions": "Is anyone going the wrong way?"
    }
  }
}

Concourse camera that opens the next gate. The state gives the area's capacity, and the instructions name the marked waiting area and the hatched exit lane.

{
  "images": [
    { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "questions": {
    "people": {
      "type": "number",
      "instructions": "How many people are there?",
      "min": 0,
      "max": 80
    },
    "crowding": {
      "type": "score",
      "instructions": "How crowded is it?",
      "criteria": ["empty", "comfortable", "busy", "crowded", "unsafe"]
    },
    "exit_blocked": {
      "type": "truth",
      "instructions": "Is the exit blocked?"
    }
  }
}

Sorter that sends every package to its lane. The state carries the line's sorting rule; the criteria say what each lane takes, what counts as damage and when a label is readable.

{
  "images": [
    { "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "questions": {
    "lane": {
      "type": "choice",
      "instructions": "Which lane?",
      "criteria": { "lane_1": "", "lane_2": "", "rework": "" }
    },
    "damaged": { "type": "truth", "instructions": "Is it damaged?" },
    "label_readable": {
      "type": "truth",
      "instructions": "Can the label be read?"
    }
  }
}

Guardrail for agent tool calls. The state keeps the user's task apart from the proposed call; the criteria say when to run, send back or block.

{
  "state": "The agent wants to run rm -rf ./ && git push --force origin main to clear the build cache.",
  "questions": {
    "verdict": {
      "type": "choice",
      "instructions": "Should the agent run this?",
      "criteria": { "run": "", "replan": "", "block": "" }
    },
    "risk": {
      "type": "score",
      "instructions": "How risky is it?",
      "criteria": ["harmless", "easy to undo", "hard to undo", "destructive"]
    },
    "in_scope": {
      "type": "truth",
      "instructions": "Is this command needed?"
    }
  }
}

Receipt and invoice checker. The state carries the claim's fields; the criteria say how a Swedish receipt writes 1315.50.

{
  "state": "Expense claim: 1315.50 SEK at Hallon Bistro on 2026-09-28.",
  "images": [
    { "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "questions": {
    "total_matches": {
      "type": "truth",
      "instructions": "Does the total match?"
    },
    "date_matches": {
      "type": "truth",
      "instructions": "Does the date match?"
    },
    "currency": {
      "type": "choice",
      "instructions": "What currency is it?",
      "criteria": { "SEK": "", "NOK": "", "EUR": "", "USD": "" }
    },
    "legible": {
      "type": "score",
      "instructions": "Is it readable?",
      "criteria": ["unreadable", "partly readable", "fully readable"]
    },
    "alcohol": { "type": "truth", "instructions": "Any alcohol?" }
  }
}

Age gate on a sign-up selfie. The state gives the minimum age and the stated birth year; the criteria say what fits them.

{
  "state": "Account birth year 2004.",
  "images": [
    { "id": "selfie", "media_type": "image/jpeg", "data": "<base64>" }
  ],
  "boosters": ["age"],
  "questions": {
    "adult": { "type": "truth", "instructions": "Is this person an adult?" },
    "matches_stated": {
      "type": "truth",
      "instructions": "Does this match the birth year?"
    },
    "age_band": {
      "type": "choice",
      "instructions": "How old are they?",
      "criteria": {
        "under_13": "",
        "teen": "",
        "young_adult": "",
        "adult": ""
      }
    }
  }
}

Structured instructions#

instructions can be an object or an array instead of a string. Put the question in one field and the data it refers to in others. The field names are yours (none is reserved), and the model reads the names together with the values, so name them for what they hold. Data fields may be empty: "", null or []. An object or array is read as compact JSON, the same way as the state.

JSON
{
  "duplicate": {
    "type": "truth",
    "instructions": {
      "question": "Is `potential_duplicate` the same order as `ticket.order`?",
      "potential_duplicate": {
        "id": "A-1182",
        "total": "49.00",
        "placed": "2026-10-04"
      },
      "note": "Treat a different currency as a different order."
    }
  }
}
  • References are read, not resolved. A state key written in backticks (ticket_message), a dot-and-index path (ticket.messages[0].text) or the name of a sibling field reaches the model exactly as written, and the model reads it. The server does not look anything up or substitute values.
  • Any phrasing works. A question ("Does this message express urgency?"), a statement to judge ("The customer asks for a refund"), a noun phrase ("How frustrated the customer appears") or an imperative ("Determine the category of this ticket").
  • References work inside criteria too, for example an option described as the amount in claim.total.

How questions are answered#

  • Independently. An answer does not depend on which other questions are in the request or on their order. Ten questions in one request get the same answers as ten requests with one question each, for the state's tokens once.
  • Without chaining. One answer is never input to another. When a decision depends on an earlier answer, send a second request built from the first answer.
  • Every time, with what there is. With little evidence, or no state, a question is still answered: a choice or a score gets a spread distribution with low confidence, a truth a value near 0.50. That is an answer, not an error, and your threshold treats it as unsure.
  • Even when the premise does not hold. A question that does not apply to the state, such as the severity of a bug on a billing ticket, still gets a complete, valid answer and does not disturb the others.
  • With one of your options. A choice always picks one of your keys, even when none fits. Add an option such as "other": "none of these" when that can happen.
  • All or nothing. A request succeeds for every question or fails as a whole. There are no partial answers. See Errors.
previousStatenextChoice

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. The questions map
  2. Question fields
  3. Writing questions that work
  4. Better answers: give it the facts and the rule
  5. How to write it
  6. In the playground examples
  7. Structured instructions
  8. How questions are answered