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…
  • Batch jobsPatternsSend up to 10,000 requests in one file and collect the answers later, at half the live price.
  • Pricing and billingYou pay for input tokens only. Output is free because the model generates no text.
↑↓ moveopen7 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • Playground
  • Console and keys
  • With coding agents
  • Examples

Concepts

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

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits
  • Versions
  • Dedicated capacity

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs

API reference

  • Overview
  • POST/v1/decide
  • GET/v1/models
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

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

Policies

  • Responsible use
  • Data and privacy

Migrate

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

Get started

  • Introduction
  • Quickstart
  • Playground
  • Console and keys
  • With coding agents
  • Examples

Concepts

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

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits
  • Versions
  • Dedicated capacity

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs

API reference

  • Overview
  • POST/v1/decide
  • GET/v1/models
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

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

Policies

  • Responsible use
  • Data and privacy

Migrate

  • Coming from a Jev-shaped API
  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 half price 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-latest and decisionnode-flash-latest, or a pinned version such as decisionnode-1.0
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
Rate limits
Per key and per model, counted per minute; see Rate limits

Endpoints#

  • POST /v1/decide

    What it does
    Answers typed questions about a state and optional images: choice, score, truth or number

  • GET /v1/models

    What it does
    Lists the models your key can send, with their limits, session limits and batch prices

  • 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/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 and optional images: choice, score, truth or number
GET /v1/modelsLists the models your key can send, with their limits, session limits and batch prices
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/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 half the live price
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 half the live price

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_. Keep them on your server, in an environment variable such as DECISIONNODE_API_KEY, never in a browser or an app. A missing, unknown or revoked key gets 401; batches and sessions belong to the key that created them.

Conventions#

  • JSON. Bodies are UTF-8 JSON with Content-Type: application/json; batch uploads may be JSON Lines (application/x-ndjson), 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-latest and decisionnode-flash-latest move to each new release. A pinned id such as decisionnode-1.0 never changes, and every response names the version that answered: model in the body, x-decisionnode-model in the headers. GET /v1/models lists what each alias points to today.

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.

Coming from a Jev-shaped API?

/v1/decide takes the same request shape and returns the same response shape, and noul is accepted as an alias of truth. Two more paths answer the same body: /api/v1/decide, an alias for proxy-style clients, and /v1/systemone, a strict path for the official SDKs. See Coming from a Jev-shaped API.

previousBatch jobsnextPOST /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

on this page

  1. Endpoints
  2. Which call to use
  3. Authentication
  4. Conventions
  5. Versions
  6. Errors and limits