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

Create a batch

Upload requests as JSON Lines or a JSON array and get a batch in state draft. Nothing runs until you finalize it.

on this page6 sections
  1. Authentication
  2. Request body
  3. Response
  4. Errors
  5. Limits
  6. Notes
POSThttps://api.decisionnode.com/v1/batches
API=https://api.decisionnode.com/v1

curl "$API/batches" \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @tickets.jsonl

Authentication#

Authorizationheaderrequired
Bearer dn_live_..., a Full access key: a Decisions-only key gets 403 key_scope_denied, "This key may only make decisions." A batch belongs to the key that created it: other keys, even in the same workspace, get 404 for it.
Content-Typeheader
application/x-ndjson for JSON Lines, application/json for an array. The API also reads the first byte: [ opens an array, { a line. Not read by the API: the first byte that is not whitespace decides, [ an array and { JSON Lines; a byte-order mark at the very start is skipped. A Content-Encoding other than identity is 400 api_usage_error, "Compressed uploads are not accepted."

Request body#

JSON Lines, one request per line, or a JSON array of the same objects. Each request is a /v1/decide body plus custom_id. An empty body or [] creates an empty draft you fill with Add requests.

{"custom_id":"ticket-48213","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"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}
{"custom_id":"ticket-48214","model":"decisionnode","state":"Customer: The app crashes every time I open the invoices tab.","questions":{"route":{"type":"choice","instructions":"Where should this go?","criteria":{"billing":"money","bug":"broken","account":"login"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}
{"custom_id":"ticket-48215","model":"decisionnode","state":"Customer: My login stopped working after I changed my email address.","questions":{"route":{"type":"choice","instructions":"Where should this go?","criteria":{"billing":"money","bug":"broken","account":"login"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}

Each request

custom_idstringrequired
Your id for the request: 1 to 512 characters, unique in the batch. Its result line carries it back.
modelstringdefault "decisionnode"
decisionnode, decisionnode-flash or a pinned version, and left out it is decisionnode, exactly as on /v1/decide. It sets the line's price. One batch may mix models. An unknown name makes that line a failed line with the live 400; the rest of the batch runs.
statestring | object | array
The input to decide about, as on /v1/decide.
imagesarray
Images, as on /v1/decide: base64 in data, by url, or an upload named by upload_id. Base64 counts toward the upload size and toward the line limit, 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string; an image by url or upload_id counts toward neither, so send large images as uploads. Up to the model's limit of 16 a line; a DecisionNode Flash line with more than 8 can wait longer: see Lines with many images.
questionsobjectrequired
The questions, as on /v1/decide: choice, score, truth, number, point or box.

Response#

201 Created with the batch object in state draft. counters.requests counts every line; lines refused for their shape are already counted in failed.

201 Created
{
  "id": "batch_01J9ZB8Q3T",
  "state": "draft",
  "counters": {
    "requests": 3,
    "queued": 0,
    "in_progress": 0,
    "completed": 0,
    "failed": 0,
    "expired": 0,
    "cancelled": 0
  },
  "created_at": "2026-10-06T09:12:04Z",
  "finalized_at": null,
  "expires_at": null,
  "ended_at": null,
  "results_url": null,
  "results_expire_at": null,
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "error": null
}
  1. Authentication
  2. Request body
  3. Response
  4. Errors
  5. Limits
  6. Notes
request
API=https://api.decisionnode.com/v1curl "$API/batches" \  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \  -H "Content-Type: application/x-ndjson" \  --data-binary @tickets.jsonl

Errors#

  • 400

    Type
    api_usage_error
    When
    The upload is not usable, with one of: "The upload is neither JSON Lines nor a JSON array.", "Line {n} is not a JSON object.", "The upload is not valid UTF-8.", "Line {n} has no custom_id.", "Line {n}: custom_id must be a string of 1 to 512 characters.", "Line {n}: custom_id {id} is already in the batch.", "The batch would hold {count} requests. The limit is 10000."; or a compressed body, "Compressed uploads are not accepted."
    What to do
    Fix the upload and send it again. Nothing was created
  • 401

    Type
    authentication_error
    When
    The key is missing, unknown or revoked
    What to do
    Check the Authorization header
  • 402

    Type
    insufficient_credit
    When
    The workspace cannot pay: details.reason plan_required, trial_allowance_used or allowance_used on a workspace with members, balance_empty on an agent workspace (Plan required)
    What to do
    Add credit or fix the plan in the console, then call again
  • 403

    Type
    key_scope_denied
    When
    A Decisions-only key: "This key may only make decisions." Checked before the rate
    What to do
    Use a Full access key on your server
  • 403

    Type
    workspace_suspended
    When
    The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."
    What to do
    Write to us
  • 408

    Type
    request_timeout_error
    When
    "The request body did not arrive in time." No byte for 20 s, the body not complete after 1,800 s, or, after the first MiB, under 64 KiB a second over any 60 s
    What to do
    Send it again on a faster connection, or in parts with add calls
  • 413

    Type
    request_too_large_error
    When
    The upload is over 256 MiB ("The request body is over the size limit."), one line is over 25 MiB ("Line {n} is over 25 MiB."), or one line is over 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, an inline image's base64 included ("Line {n} is over 17767680 bytes as a batch job (its quotes and backslashes counted twice). Send large images as uploads (POST /v1/uploads) and name them by upload_id."); nothing is applied
    What to do
    Split it into several batches of up to 10,000 requests; send large images with POST /v1/uploads and name them by upload_id
  • 429

    Type
    batch_limit_exceeded
    When
    Your key already has 10 active batches ("This key already has 10 active batches."), or your workspace 50 ("This workspace already has 50 active batches."); Retry-After: 30
    What to do
    Finalize or cancel a draft, or wait for a batch to end
  • 429

    Type
    batch_limit_exceeded
    When
    The call would put more than 100,000 requests in your key's active batches, drafts included ("This call would put {n} requests in this key's active batches. The limit is 100000."), or more than 500,000 in your workspace's, or make your workspace's batches store more than 20.0 GiB (uploads, and results not yet deleted; checked before the body is read). Retry-After: 30
    What to do
    Wait for a batch to end, or cancel a draft you will not finalize. Nothing from the call was applied
  • 429

    Type
    rate_limit_error
    When
    Uploads in progress: "This key already has 2 uploads in progress." or "This workspace already has 4 uploads in progress.", Retry-After: 30
    What to do
    Wait for an upload to finish
  • 429

    Type
    rate_limit_error
    When
    Over your workspace's request rate (or your key's own lower limit): batch calls count against it
    What to do
    Wait Retry-After seconds, then send the same call again
  • 500

    Type
    api_error
    When
    A fault on our side
    What to do
    Retry with backoff and jitter. A 5xx can come after the call took effect: before you create again, cancel any draft the failed create left behind (see Batch errors)
  • 529

    Type
    overloaded_error
    When
    The service's upload memory or its store of batches is full right now
    What to do
    Wait Retry-After seconds, then retry
  • 529

    Type
    overloaded_error
    When
    The API cannot take the call right now
    What to do
    Wait Retry-After seconds, then retry with backoff
Errors this endpoint returns
StatusTypeWhenWhat to do
400api_usage_errorThe upload is not usable, with one of: "The upload is neither JSON Lines nor a JSON array.", "Line {n} is not a JSON object.", "The upload is not valid UTF-8.", "Line {n} has no custom_id.", "Line {n}: custom_id must be a string of 1 to 512 characters.", "Line {n}: custom_id {id} is already in the batch.", "The batch would hold {count} requests. The limit is 10000."; or a compressed body, "Compressed uploads are not accepted."Fix the upload and send it again. Nothing was created
401authentication_errorThe key is missing, unknown or revokedCheck the Authorization header
402insufficient_creditThe workspace cannot pay: details.reason plan_required, trial_allowance_used or allowance_used on a workspace with members, balance_empty on an agent workspace (Plan required)Add credit or fix the plan in the console, then call again
403key_scope_deniedA Decisions-only key: "This key may only make decisions." Checked before the rateUse a Full access key on your server
403workspace_suspendedThe workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."Write to us
408request_timeout_error"The request body did not arrive in time." No byte for 20 s, the body not complete after 1,800 s, or, after the first MiB, under 64 KiB a second over any 60 sSend it again on a faster connection, or in parts with add calls
413request_too_large_errorThe upload is over 256 MiB ("The request body is over the size limit."), one line is over 25 MiB ("Line {n} is over 25 MiB."), or one line is over 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, an inline image's base64 included ("Line {n} is over 17767680 bytes as a batch job (its quotes and backslashes counted twice). Send large images as uploads (POST /v1/uploads) and name them by upload_id."); nothing is appliedSplit it into several batches of up to 10,000 requests; send large images with POST /v1/uploads and name them by upload_id
429batch_limit_exceededYour key already has 10 active batches ("This key already has 10 active batches."), or your workspace 50 ("This workspace already has 50 active batches."); Retry-After: 30Finalize or cancel a draft, or wait for a batch to end
429batch_limit_exceededThe call would put more than 100,000 requests in your key's active batches, drafts included ("This call would put {n} requests in this key's active batches. The limit is 100000."), or more than 500,000 in your workspace's, or make your workspace's batches store more than 20.0 GiB (uploads, and results not yet deleted; checked before the body is read). Retry-After: 30Wait for a batch to end, or cancel a draft you will not finalize. Nothing from the call was applied
429rate_limit_errorUploads in progress: "This key already has 2 uploads in progress." or "This workspace already has 4 uploads in progress.", Retry-After: 30Wait for an upload to finish
429rate_limit_errorOver your workspace's request rate (or your key's own lower limit): batch calls count against itWait Retry-After seconds, then send the same call again
500api_errorA fault on our sideRetry with backoff and jitter. A 5xx can come after the call took effect: before you create again, cancel any draft the failed create left behind (see Batch errors)
529overloaded_errorThe service's upload memory or its store of batches is full right nowWait Retry-After seconds, then retry
529overloaded_errorThe API cannot take the call right nowWait Retry-After seconds, then retry with backoff

Every error body is {"detail": {"error_type": "...", "message": "..."}}. Retry 408, 429 (rate_limit_error), 529 and any 5xx, waiting at least what Retry-After says when it is set; fix the call for the other 4xx. A 429 batch_limit_exceeded clears only when a batch ends or you cancel one. All the bodies are on Errors.

Limits#

  • Requests

    Value
    Up to 10,000
  • Upload

    Value
    256 MiB, images included
  • One line

    Value
    25 MiB as sent, and in effect 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, which is how a batch job carries the line: each ", \, tab and newline counts twice. An inline image's base64 counts toward it; an image by url or upload_id does not
  • custom_id

    Value
    1 to 512 characters, unique in the batch
  • Each request

    Value
    The live limits of /v1/decide
  • Requests in active batches per key

    Value
    100,000, drafts included, checked on this call
Limits that apply to this call
LimitValue
RequestsUp to 10,000
Upload256 MiB, images included
One line25 MiB as sent, and in effect 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, which is how a batch job carries the line: each ", \, tab and newline counts twice. An inline image's base64 counts toward it; an image by url or upload_id does not
custom_id1 to 512 characters, unique in the batch
Each requestThe live limits of /v1/decide
Requests in active batches per key100,000, drafts included, checked on this call

Notes#

  • A line the API refuses for its shape (an unknown model, a question with no options, a field of the wrong type, a point or box question asking for max, which is the 422 not_supported) is accepted into the batch as a failed line with the live status and body and an x-decisionnode-error header naming the refusal, and never runs. The rest of the batch is unaffected.
  • Limits counted in tokens, such as the per-request token limit, are checked when the line runs: such a line comes back as the live 400.
  • A refused upload leaves nothing behind: no draft, no lines.
  • The draft counts toward your 10 active batches until you finalize or cancel it; a draft not finalized within 24 hours of created_at is cancelled.
previousThe batch objectnextAdd requests

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