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, no SDK to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state and optional images. 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.
  • ImagesConceptsSend images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and answers…
  • Pricing and billingYou pay for input tokens only. Output is free because the model generates no text.
↑↓ moveopen6 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • With coding agents
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Images
  • Confidence
  • Determinism

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loopscomingcoming soon

API reference

  • POST/v1/decide
  • POST/v1/sessionscomingcoming soon
  • GET/v1/models
  • Errors
  • Rate limits

Pricing and billing

  • Pricing and billing

Policies

  • Responsible use

Migrate

  • Coming from a Jev-shaped API
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • With coding agents
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Images
  • Confidence
  • Determinism

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loopscomingcoming soon

API reference

  • POST/v1/decide
  • POST/v1/sessionscomingcoming soon
  • GET/v1/models
  • Errors
  • Rate limits

Pricing and billing

  • Pricing and billing

Policies

  • Responsible use

Migrate

  • Coming from a Jev-shaped API
  1. docs
  2. /
  3. API reference

POST /v1/decide

Answer typed questions about a state and optional images. One request, one buffered JSON response, one answer per question.

on this page5 sections
  1. Headers
  2. Request body
  3. Response body
  4. Response headers
  5. Errors
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-latest",
    "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?"
      }
    }
  }'

Headers#

Authorizationstringrequired
Bearer dn_live_.... Keep keys on your server and read them from an environment variable such as DECISIONNODE_API_KEY.
Content-Typestringrequired
application/json.

Request body#

modelstringrequired
decisionnode-latest or decisionnode-flash-latest, or a pinned version such as decisionnode-1.0.
statestring | object | array
The input to decide about: text, a JSON object or a JSON array. Read once and shared by every question.
imagesarray
Up to 4 images, read together with the state.
idstringrequired
Your name for the image.
media_typestringrequired
image/jpeg, image/png or image/webp.
datastringrequired
Base64 bytes, no data: prefix.
questionsobjectrequired
Your question keys mapped to question objects. Answers come back under the same keys.
type"choice" | "score" | "truth" | "number"required
Fixes the answer's shape: choice, score, truth or number.
instructionsstring
What to decide, in one sentence.
criteriaobject | string[]
Choice: option key to description, required, up to 255. Score: levels lowest first, required, up to 10. Truth: optional {"true": "...", "false": "..."}, what true and what false mean. Number: not used, the grid is the set of answers.
minnumber
Number only: the lowest value. Default 0.
maxnumber
Number only: the highest value, at least min. Default 255.
stepnumber
Number only: the grid spacing, above 0. Default 1. Up to 256 values in the first release; see Number.

Response body#

JSON
{
  "model": "decisionnode-1.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
    },
    "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 }
    },
    "refund": { "type": "truth", "truth": 0.94 }
  },
  "usage": { "input_tokens": 62, "output_tokens": 0 }
}
modelstring
The pinned version that answered, for example decisionnode-1.0.
answersobject
One answer per question key.
choice answerobject
type, choice (one of your keys), confidence, probabilities (alphabetical by key).
score answerobject
type, score (expected level index), confidence, legend, probabilities (in level order).
truth answerobject
type ("truth") and truth, the probability that the statement is true, from 0.00 to 1.00.
number answerobject
type, number (the most probable grid value), expected (the probability-weighted mean), confidence (the probability of number), probabilities (every value above 0.001, keyed by the value as a string).
usageobject
input_tokens billed for this request, and output_tokens, which is always 0.

Rules of the shape

Numbers are rounded to 2 decimals. A choice's confidence is (K × p_max − 1) / (K − 1) for K options. A score is the expected level index, and its confidence is 1 − E[|level − mode|] / D(K), where mode is the most likely level and D(K) = floor(K × K / 4) / K. Both confidences are computed before rounding. A truth answer carries only type and truth. A number answer's confidence is the probability of number, and its expected is the sum of each value times its probability. See Confidence.

Compatibility: the noul alias

A question sent with "type": "noul" is accepted as the same type as truth and answered in its own name, { "type": "noul", "noul": 0.94 }, so code written for a Jev-shaped API keeps working unchanged. New code should send truth. See Coming from a Jev-shaped API.

  1. Headers
  2. Request body
  3. Response body
  4. Response headers
  5. Errors
request
curl https://api.decisionnode.com/v1/decide \  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "decisionnode-latest",    "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?"      }    }  }'

Response headers#

  • x-request-id

    Example
    req_01J9Z6K4M2
    Meaning
    Quote it when you contact us; store it with the decision

  • x-decisionnode-latency-ms

    Example
    6
    Meaning
    Time spent on our side, in milliseconds

  • x-decisionnode-model

    Example
    decisionnode-1.0
    Meaning
    The model version that answered, as in model

  • Retry-After

    Example
    2
    Meaning
    Seconds to wait before retrying, sent with every 429 and 529
Response headers
HeaderExampleMeaning
x-request-idreq_01J9Z6K4M2Quote it when you contact us; store it with the decision
x-decisionnode-latency-ms6Time spent on our side, in milliseconds
x-decisionnode-modeldecisionnode-1.0The model version that answered, as in model
Retry-After2Seconds to wait before retrying, sent with every 429 and 529

Errors#

  • 400

    Meaning
    Outside a limit (options, levels, 64k tokens, a number grid the first release does not serve), an unknown model or a bad image; the message names it

  • 401

    Meaning
    Missing or invalid API key

  • 402

    Meaning
    Out of credit; add credit in the console, then retry. Not billed. See Errors

  • 403

    Meaning
    Refused by the safety check (safety_refusal); rolling out in shadow mode, see Errors

  • 422

    Meaning
    The body failed validation; detail lists each invalid field

  • 429

    Meaning
    Rate limited; wait for Retry-After

  • 529

    Meaning
    Overloaded; wait for Retry-After, then retry
Error statuses
StatusMeaning
400Outside a limit (options, levels, 64k tokens, a number grid the first release does not serve), an unknown model or a bad image; the message names it
401Missing or invalid API key
402Out of credit; add credit in the console, then retry. Not billed. See Errors
403Refused by the safety check (safety_refusal); rolling out in shadow mode, see Errors
422The body failed validation; detail lists each invalid field
429Rate limited; wait for Retry-After
529Overloaded; wait for Retry-After, then retry

Bodies, retry rules and code are in Errors.

Deciding many times a second?

/v1/decide answers one request with one response. For more than 10 decisions a second about the same thing, a session comingcoming soon keeps your context loaded and streams one typed reply per frame.

previousControl loopscomingcoming soonnextSessionscomingcoming soon

DecisionNode is built and run by Bynn Intelligence, Inc.

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