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

API reference

One HTTPS API on our own inference stack: ask typed questions, stream decisions over a session, run batch jobs at a lower price than live calls and list the models your key can use. Base URL, keys, conventions and every endpoint, on one page.

on this page6 sections
  1. Endpoints
  2. Which call to use
  3. Authentication
  4. Conventions
  5. Versions
  6. Errors and limits
Base URL
https://api.decisionnode.comhttps://api.decisionnode.com
Authentication
Authorization: Bearer dn_live_... on every call; keys are created in the console
Format
JSON request and response bodies; JSON Lines for batch uploads and results
Models
decisionnode and decisionnode-flash, a pinned version such as decisionnode-main-0.9.1-rc1, or your own fine-tuned model such as decisionnode-flash@acme/fraud
Errors
A status code and a detail body; see Errors
Request id
x-request-id on every response; log it with the status
Safety
Every decision response carries x-decisionnode-safety; see Safety check
Boosters
Up to 4 specialist readings of a request's images, returned in evidence; see Boosters
Rate limits
Per workspace, shared by its keys, counted per second; see Rate limits

Endpoints#

  • POST /v1/decide

    What it does
    Answers typed questions about a state, images and video frames: choice, score, truth, number, point or box
  • POST /v1/systemone

    What it does
    The same decisions in the System One request format, for clients and benchmark harnesses written for it
  • GET /v1/models

    What it does
    Lists the models your key can send, your fine-tuned models included, with their prices, limits, upload and video limits and batch limits
  • POST /v1/uploads

    What it does
    Puts images into your workspace's storage, to name by upload_id for an hour
  • POST /v1/sessions

    What it does
    Opens a session: the fixed part of your request, sent once
  • WS /v1/sessions/{id}/stream

    What it does
    Streams frames and one typed reply per answered frame
  • DELETE /v1/sessions/{id}

    What it does
    Ends a session
  • POST /v1/credit

    What it does
    Buys prepaid credit with a machine payment: a 402 challenge, paid with a card through a Stripe Shared Payment Token, USDC on Tempo or USDC on Base; without a key, it makes an agent workspace and a key
  • POST /v1/batches

    What it does
    Creates a batch from a JSON Lines file or a JSON array
  • POST /v1/batches/{id}/requests

    What it does
    Adds requests to a draft batch
  • POST /v1/batches/{id}/finalize

    What it does
    Queues a draft to run
  • GET /v1/batches/{id}

    What it does
    Returns a batch's state and counters
  • GET /v1/batches/{id}/results

    What it does
    Returns one result line per request
  • POST /v1/batches/{id}/cancel

    What it does
    Cancels what has not started
  • GET /v1/batches

    What it does
    Lists your key's batches
Every endpoint
EndpointWhat it does
POST /v1/decideAnswers typed questions about a state, images and video frames: choice, score, truth, number, point or box
POST /v1/systemoneThe same decisions in the System One request format, for clients and benchmark harnesses written for it
GET /v1/modelsLists the models your key can send, your fine-tuned models included, with their prices, limits, upload and video limits and batch limits
POST /v1/uploadsPuts images into your workspace's storage, to name by upload_id for an hour
POST /v1/sessionsOpens a session: the fixed part of your request, sent once
WS /v1/sessions/{id}/streamStreams frames and one typed reply per answered frame
DELETE /v1/sessions/{id}Ends a session
POST /v1/creditBuys prepaid credit with a machine payment: a 402 challenge, paid with a card through a Stripe Shared Payment Token, USDC on Tempo or USDC on Base; without a key, it makes an agent workspace and a key
POST /v1/batchesCreates a batch from a JSON Lines file or a JSON array
POST /v1/batches/{id}/requestsAdds requests to a draft batch
POST /v1/batches/{id}/finalizeQueues a draft to run
GET /v1/batches/{id}Returns a batch's state and counters
GET /v1/batches/{id}/resultsReturns one result line per request
POST /v1/batches/{id}/cancelCancels what has not started
GET /v1/batchesLists your key's batches

Which call to use#

  • An answer now, for one input

    Call
    POST /v1/decide
    Billed
    Input tokens at the live price
  • More than 10 answers a second about one evolving input

    Call
    A session
    Billed
    The fixed part once, then each frame's tokens, at the live price
  • Answers for a large set nothing is waiting on

    Call
    A batch job
    Billed
    Input tokens of completed requests at 30% off the live price on DecisionNode and 50% off on DecisionNode Flash
Which call for which work
You needCallBilled
An answer now, for one inputPOST /v1/decideInput tokens at the live price
More than 10 answers a second about one evolving inputA sessionThe fixed part once, then each frame's tokens, at the live price
Answers for a large set nothing is waiting onA batch jobInput tokens of completed requests at 30% off the live price on DecisionNode and 50% off on DecisionNode Flash

All three take the same questions and return the same answers: the same request on the same model version gets the same answer, whichever way it is sent. Output is free on all three.

Authentication#

Send your key as a bearer token on every call, the session stream included. Keys start with dn_live_. A key has one of four kinds: Full access and Manage device keys keys stay on your server, in an environment variable such as DECISIONNODE_API_KEY; a device gets a Decisions-only key of its own, and only a Publishable key goes in a browser or an app. A call outside a key's kind gets 403 key_scope_denied. A missing, unknown, expired or revoked key gets 401; batches and sessions belong to the key that created them.

Conventions#

  • JSON. Bodies are UTF-8 JSON; batch uploads may be JSON Lines, one request per line.
  • Names. Fields are snake_case. Your question keys and batch custom_ids come back exactly as you sent them.
  • Numbers. Probabilities, confidences, scores and truths are rounded to 2 decimals. One exception: a number answer's probabilities are listed to 3 decimals.
  • Times. Timestamps are ISO 8601 strings in UTC, such as 2026-10-06T09:12:04Z.
  • Ids. Batch ids start with batch_, session ids with ses_, request ids with req_. Treat them as opaque strings.
  • Paging. List endpoints take offset and limit and return next_offset, null on the last page.
  • Determinism. The same request to the same model version returns the same answer. Pin a version to keep answers fixed across releases.

Versions#

decisionnode and decisionnode-flash move to each new release. A pinned id such as decisionnode-main-0.9.1-rc1 never changes, and every response names the version that answered: model in the body, x-decisionnode-model in the headers. During a rollout, while the servers move to a new version, a request may be answered by any version a server of the family reports; the header names exactly what answered. GET /v1/models names each family's current version.

Errors and limits#

Errors share one body: detail, with an error_type and a message, or a list of fields for a 422. One rule covers every endpoint: retry 408, 429, 529 and any 5xx, waiting at least what Retry-After says when it is set, and fix the request for the other 4xx. A limit or a bad request is never reported as a 5xx, so a 5xx is always safe to retry. Errors lists every status and type, Limits every size limit, and Rate limits what counts against your key.

previousROS 2nextPOST /v1/decide

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. Endpoints
  2. Which call to use
  3. Authentication
  4. Conventions
  5. Versions
  6. Errors and limits