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

Quickstart

Get an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.

on this page6 sections
  1. Get an API key
  2. Send your first request
  3. Read the answers
  4. Branch on them
  5. What just happened
  6. Next steps

This page uses plain HTTPS. The SDKs for eight languages and the dn command line send the same requests: see Choose how to call DecisionNode.

  1. 1

    Get an API key#

    Open the console, go to API keys and choose Create key. The key is shown once, so copy it straight into your environment. Keys start with dn_live_; a key with full access, the default, works with both models and every endpoint. Console, keys and members covers rotation and team access.

    Shell
    export DECISIONNODE_API_KEY="dn_live_..."
  2. 2

    Send your first request#

    Post a state and your questions to https://api.decisionnode.com/v1/decidehttps://api.decisionnode.com/v1/decide. This one routes a support message, ranks its urgency and asks whether to refund it automatically.

    curl https://api.decisionnode.com/v1/decide \
      -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "decisionnode",
        "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?"
          }
        }
      }'
  3. 3

    Read the answers#

    Each answer comes back under the key you gave its question. The route is billing with confidence 0.81, the urgency sits at 2.31 on your 0 to 3 scale, and the refund probability is 0.94. That last one is a Truth answer: the calibrated probability, from 0.00 to 1.00, that the statement is true, here that this charge should be refunded automatically. 0.80 means true about 8 times in 10 on our evaluation data. Your code picks the cut-off: 0.50 for a plain yes or no, higher when acting on a false yes is costly, as with a refund.

    Response
    {
      "model": "decisionnode-main-0.9.1-rc1",
      "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,
        "cost": {
          "usd": 0.000002604,
          "model_usd": 0.000002604,
          "boosters_usd": 0,
          "free_tier": false
        }
      }
    }
  4. 4

    Branch on them#

    Answers are numbers and keys, so your code acts on them the moment they land. Sure cases go straight through; unsure ones take the safe path, still automatically.

    route = answers["route"]
    urgency = answers["urgency"]
    refund = answers["refund"]
    
    if refund["truth"] >= 0.8:              # sure: refund now
        issue_refund(ticket)
        reply(ticket, template="refund_issued")
    elif route["confidence"] < 0.7:        # unsure: safe path
        reply(ticket, template="ask_for_order_id")
    else:                                  # sure: route it
        priority = round(urgency["score"])
        assign(ticket, route["choice"], priority)

No key yet?

The playground runs the same request shapes in the browser, shows the answers as charts and copies the request as curl, Python or TypeScript. It needs an account and no key, and its runs are billed to your workspace's plan. See Playground.

Call it from your server

The API refuses calls from browsers, except POST /v1/decide with a publishable key from an origin it lists: a frontend fetch of any other route these docs describe fails at the cross-origin preflight with 400 Disallowed CORS origin. Send requests from your backend, which holds the key, and let your frontend call your backend; a device gets a key of its own.

What just happened#

  • The model read the state once and answered all three questions in one pass, with decisionnode.
  • It generated no text: usage.output_tokens is always 0, and output is free.
  • The request used 62 input tokens. At $0.042 per million, a million of these requests cost about $2.60.
  • Up to 64k tokens fit in one request, so the state can be a whole thread or a JSON record.
  • Your requests and their answers improve our models unless you opt out in the console. With zero retention, requests and answers sent to /v1/decide are not stored once the answer is returned and are not used to improve the models; sessions, batches and safety records are described in Data and privacy, which also says how to opt out.
  • Choice, score and truth are three of the question types. Number answers how many or what value, on a grid you set, and point and box answer where in an image.

Next steps#

  • Write better questionsOptions, scales and instructions that the model reads well.Read
  • Gate on confidenceAct above a threshold, re-check the unsure middle with the full model, and take the safe path below it.Read
  • Add an imageReceipts, photos and screenshots in the same request.Read
  • Handle errors400 to 529: which to fix, which to retry, and what to do when credit runs out.Read
previousIntroductionnextCommand line

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. Get an API key
  2. Send your first request
  3. Read the answers
  4. Branch on them
  5. What just happened
  6. Next steps