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

POST /v1/decide

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

on this page9 sections
  1. Headers
  2. Request body
  3. Response body
  4. Response headers
  5. Repeated requests
  6. Boosters
  7. Errors
  8. Limits
  9. Notes
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",
    "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?"
      }
    }
  }'

Answers every question in the request about one state and its images, in one pass, and returns them together in one JSON body. A request succeeds for every question or fails as a whole.

Headers#

Authorizationstringrequired
Bearer dn_live_.... Keep keys on your server and read them from an environment variable such as DECISIONNODE_API_KEY. The API refuses calls from browsers, except POST /v1/decide with a publishable key from an origin it lists: a cross-origin preflight for any other route these docs describe gets 400 Disallowed CORS origin, so a frontend calls your backend and your backend calls DecisionNode.
Content-Typestring
application/json. Not checked: the body is read as JSON whatever its type.
x-decisionnode-safety-bodystringdefault off
true, 1 or yes adds a top-level safety object to a 200 body: what the safety check found, to four decimals. Without it the body holds only model, answers and usage.
x-decisionnode-cachestring
bypass skips the cache of repeated requests: the answer is computed and billed, carries bypass, and is still stored for repeats when it can be cached.

Request body#

modelstringdefault "decisionnode"
decisionnode or decisionnode-flash, a pinned version such as decisionnode-main-0.9.1-rc1, or a fine-tuned model of your workspace: <base>@<workspace>/<name>, such as decisionnode-flash@acme/fraud, with :<version> to pin one. Any other name, a fine-tuned version that is not deployed and another workspace's model included, is a 400 Unknown model. See Versions.
fallbackbooleandefault true
What happens when DecisionNode has no ready capacity. true: a request for decisionnode (the family, or an earlier alias of it) is answered at once by decisionnode-flash-0.9.1-rc1, billed at DecisionNode Flash's price, and says so: model names DecisionNode Flash, and the x-decisionnode-fallback and x-decisionnode-requested-model headers name both models. false: the request gets 529 overloaded_error with Retry-After: the rest of DecisionNode's boot window when it is starting (up to 600 s), 30 s when it is unhealthy, 1 s when nothing serves it. A workspace whose fallback policy is never is always answered as false. Only this call falls back, and only for the family id: a pinned version, DecisionNode Flash, fine-tuned models, sessions and batch lines never do. A publishable key is answered by the fallback only when the fallback is one of its models; otherwise its call gets the 529 it would without one. See No ready capacity.
statestring | object | arraydefault ""
The input to decide about: text, a JSON object or a JSON array. Read once and shared by every question. Leave it out, or send an empty string, when the questions carry everything. A bare number or boolean is a 422.
imagesarraydefault []
Up to 16 images within the request's token limit, each up to 10 MB and 40 megapixels, read together with the state in array order and seen by every question. Each is resized so its longest side fits 2,048 px, and its metadata is stripped. null and [] mean no images. See Images.
idstringrequired
Your name for the image, unique within the request and at most 64 characters: a short, meaningful name such as receipt, not a digit. With two or more images, say in each question which image it is about, by this id in backticks ("Does claim_photo show visible damage?") or by its number from 1 in array order ("image 2"). See Referring to images and videos.
datastring
Base64 bytes, no data: prefix. Send one of data, url and upload_id.
urlstring
An https address the server fetches the image from, at most 2,048 characters. Send one of data, url and upload_id.
upload_idstring
An image you put in storage with POST /v1/uploads, named by any key of your workspace for one hour. Send one of data, url and upload_id.
media_typestring
image/jpeg, image/png or image/webp. Required with data; optional with url and upload_id, where it must match the image when given.
videosarraydefault []
Up to 4 videos, each sent as frames with their timestamps (id, frames, optional fps, start and end), read as one video with order and timing and seen by every question. Questions refer to a video by its id or by its number ("video 1"), counted from 1 in array order and separately from the images. Video files and URLs are not taken. See Video.
boostersarraydefault []
Up to 4 boosters, each named once: specialist models that read the request's images before the decision; their readings come back in evidence. An entry is a name ("age", "ai_generated", "face_detection", "face_recognition", "ocr", "bynn_depth", "bynn_segment" or "knowledge") or an object. null and [] mean no boosters. Priced per picture read: age (Human Age) $0.024, ai_generated (AI-generated) $0.006, face_detection (Face detection) $0.001, face_recognition (Face recognition) $0.001 on your own collection and $0.001 on celebrities, ocr (OCR) $0.0015, bynn_depth (Depth Vision) free, bynn_segment (Segment Vision) $0.001 and knowledge (Knowledge) $0.001 a request.
namestringrequired
The booster's name: age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment or knowledge. Another name is a 400 booster_unknown.
imagesarraydefault every image
The ids of the images it reads. An id that is not an image of the request is a 400 booster_input_mismatch.
timeout_msintegerdefault the booster's budget
Its time budget for this request, in milliseconds, from 100 to the booster's ceiling (max_deadline_ms in the catalogue; the defaults and ceilings: 2 s up to 5 s for age, 5 s up to 6 s for ai_generated, 2 s up to 5 s for face_detection, 2 s up to 5 s for face_recognition, 12 s up to 12 s for ocr, 800 ms up to 5 s for bynn_depth, 1.5 s up to 5 s for bynn_segment and 800 ms up to 5 s for knowledge). Outside that range or not an integer is a 422 at ["body", "boosters", <i>, "timeout_ms"] (int_type, greater_than_equal, less_than_equal), and nothing runs. On the OpenAI-compatible route, the 400 with param boosters[<i>].timeout_ms.
requirebooleandefault false
true: a booster that fails or runs out of time fails the request with 529 booster_unavailable. false: the decision runs without that reading.
optionsobject
A booster's settings, each listed under its booster below. Another key, a key on a booster that takes none, or a value out of range is a 400 api_usage_error.
questionsobjectrequired
Your question keys mapped to question objects, at least one. A key is any string, with no length limit of its own, and answers come back under the same keys byte for byte. The model never sees the keys. There is no count limit: the token limit is the only bound. The order of fields inside a question does not matter.
type"choice" | "score" | "truth" | "number" | "point" | "box"required
Fixes the answer's shape: choice, score, truth, number, point or box. "point" and "box" answer where in an image. See Points and boxes.
instructionsstring | object | array
What to decide, in one sentence. An object or an array may carry the question in one field and the data it refers to in others; it is read as compact JSON, and references in it are read by the model, not resolved by the server. See Structured instructions. Optional on a choice and a score, which can be answered from their options or levels alone. A number question needs instructions: without them, or with "", it is a 400, "Number question must have instructions: <key>". A truth question needs instructions or criteria: with neither, it is a 400.
criteriaobject | array
Choice: option name to description, required, 1 to 255; a name is any string and comes back byte for byte, a description is a string, an object, an array or null. Score: levels lowest first, required, up to 10; each a string, an object or an array, echoed in legend as sent. Truth: optional {"true": "...", "false": "..."}, what true and what false mean; null and {} mean no criteria. Number: not used, the grid is the set of answers.
minnumberdefault 0
Number only: the lowest value.
maxnumberdefault 255
Number only: the highest value, at least min.
stepnumberdefault 1
Number only: the grid spacing, above 0, such as 0.5 for halves or 0.1 for one decimal. Up to 256 values are one question; finer or wider grids are composed in the same call, up to 4,096 values in all. See Number.
imagestring
Point and box only: the id of the image to look in, a string, never a number. Required when the request carries two or more images. The instructions can still refer to other images: "Draw a box around the package from picture 1" with "image": "dock_3".
units"pixels" | "normalized"default "pixels"
Point and box only: pixels of the image as sent, or normalized fractions of the width and the height from 0 to 1.

An optional field sent as null is the same as leaving it out. Top-level fields this page does not list, such as temperature, are ignored, and so are fields inside a question that its type does not use. A body nests at most 128 objects and arrays deep.

Response body#

JSON
{
  "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
    }
  }
}
modelstring
The pinned version that answered, for example decisionnode-main-0.9.1-rc1; for a fine-tuned model its pinned name, such as decisionnode-flash@acme/fraud:3. On a fallback answer it is decisionnode-flash-0.9.1-rc1, the model that answered, not the one you asked for.
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, written as your grid writes it: 7 on a whole-number grid, 3.5 on a grid of 0.5), expected (the probability-weighted mean, a float such as 7.3 or 7.0), confidence (the probability of number), probabilities (every value whose probability is above 0.001 before rounding, keyed by the value as a string, each to 3 decimals; they sum to at most 1). Read number as a float in a typed client; it always equals a value of your grid.
point answerobject
type, x and y (the spot, from the top-left corner), present (the probability that the thing is in the image at all), confidence (meant as the probability that the spot is on it; not calibrated yet, so gate on present), image, width and height. See Points and boxes.
box answerobject
type, x1, y1 (top-left) and x2, y2 (bottom-right), present, confidence (meant as the probability that the box overlaps the true one by an intersection over union of 0.5 or more; not calibrated yet, so gate on present), image, width and height.
usageobject
input_tokens billed for this request, and output_tokens, which is always 0. A request with videos also gets video_frames and video_seconds. A request that named boosters also gets booster_tokens, the part of input_tokens the readings take, and boosters, the booster calls billed.
costobject
What this answer cost, on every answer: the amount booked for it, in USD at your workspace's rates. A refused or unbilled answer carries it with every amount 0. No response header carries it.
usdnumber
What the answer booked, model_usd plus boosters_usd: a number with up to 9 decimals, never a string.
model_usdnumber
The model's part: the input tokens at the model's prices for text, images and video.
boosters_usdnumber
The boosters' part: each booster's billed calls at its price. 0 without boosters; a test call adds 0.
free_tierboolean
true only when a daily free count covered the model's request. Workspaces have no free daily counts, so it is false; test calls are free without it.
evidenceobject
Only on a request that named boosters: one entry per booster, in the request's order, keyed by its name. A request the safety check refused carries none. See Boosters.
versionstring
The booster version that read, <name>-v<n>, such as age-v3.
statusstring
ok, timeout, error, skipped: read, ran out of its time, failed, or found no image it reads.
latency_msinteger
How long the booster took.
billed_callsinteger
The calls of this booster billed on this request: one per image it read with status ok, every time a request uses it; 0 only for a booster that timed out, failed or was skipped, a picture it could not decode, and a refused request. With a price per booster, a request's booster cost is each entry's billed_calls times that booster's price; usage.boosters is the total.
resultsarray
One entry per picture, named by image. On ok, each carries the booster's fields below, or "readable": false for a picture it could not decode (not billed). On timeout or error, one bare {"image": id} per picture it was meant to read, and billed_calls is 0. On skipped, empty.

Rules of the shape

Numbers in answers are JSON floats rounded to 2 decimals, and whole values keep their decimal point (1.0, 0.0). One exception: a number answer's number is a value of your grid and is written as the grid writes it, 7 on a whole-number grid and 3.5 on a grid of 0.5; its expected and confidence follow the float rule, and its probabilities are listed to 3 decimals, with no correction toward a sum of 1, so the listed values sum to at most 1. usage counts are integers. confidence, score and truth are always clean two-decimal values; an entry of a choice's or a score's probabilities nudged by 0.01 toward a sum of 1 can print as 0.8200000000000001, and a few of those lists sum to 0.99 or 1.01. choice is taken from the unrounded probabilities, a tie goes to the option first in your request, and the named option can be 0.01 below the largest value shown. 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.

  1. Headers
  2. Request body
  3. Response body
  4. Response headers
  5. Repeated requests
  6. Boosters
  7. Errors
  8. Limits
  9. Notes
request
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?"      }    }  }'

Response headers#

  • x-request-id

    Example
    req_3f6c1a9e0b2d4c7f8a1e5d9b
    Meaning
    On every response, errors included: req_ and 24 lowercase hex digits. Quote it when you contact us; store it with the decision. A request that sends its own x-request-id in that shape keeps it
  • x-decisionnode-request-id

    Example
    req_3f6c1a9e0b2d4c7f8a1e5d9b
    Meaning
    The same id as x-request-id, on every response
  • x-decisionnode-latency-ms

    Example
    71.0
    Meaning
    Time the model took on our side, in milliseconds with one decimal; on a cache hit, the hit's own time
  • x-decisionnode-model

    Example
    decisionnode-main-0.9.1-rc1
    Meaning
    The model version that answered, as in model; a fine-tuned model's pinned name
  • x-decisionnode-boosters

    Example
    age=ok:212,ai_generated=timeout:800
    Meaning
    On the answer of a request that named boosters, and on its errors once the boosters ran (booster_unavailable, a later 529, the model's errors): each booster's status and time in milliseconds, in the request's order. Not on an error raised before they run: a malformed boosters, booster_unknown, booster_not_enabled, booster_input_mismatch, key_scope_denied, a collection error, 401, 402 or 429
  • x-decisionnode-fallback

    Example
    decisionnode-flash-0.9.1-rc1
    Meaning
    Only on a fallback answer: the model that answered in place of DecisionNode, as in model
  • x-decisionnode-requested-model

    Example
    decisionnode-main-0.9.1-rc1
    Meaning
    Only on a fallback answer: the model the request asked for
  • x-decisionnode-cache

    Example
    hit
    Meaning
    On every /v1/decide response, errors included: hit on an answer served from the cache of repeated requests; miss when the cache was looked up and held nothing; bypass when it was not looked up (the request header, zero retention, a request that cannot be cached, or an error before the lookup)
  • x-decisionnode-safety

    Example
    harm=0.002, self_harm=0.001
    Meaning
    On every decision response, a 403 included: each category's probability, ;flagged above your key's threshold, ;blocked on a refusal, or unchecked with a reason. See Safety check
  • x-decisionnode-image-tokens

    Example
    1174
    Meaning
    When above 0: the part of usage.input_tokens that came from images
  • x-decisionnode-video-tokens

    Example
    5120
    Meaning
    When above 0: the part of usage.input_tokens that came from videos
  • x-decisionnode-error

    Example
    question 'urgency': a score takes up to 10 levels, got 11
    Meaning
    What is wrong, in words, on the errors that say it: api_usage_error, the upload errors, a malformed boosters (the reason), booster_input_mismatch, a booster timeout_ms out of range, and every error the model's server sends (max_tokens_exceeded's count and limit travel here). Not on 401, 402, 403 (workspace_suspended, booster_not_enabled, key_scope_denied, collection errors), 404, 405, 408, 413, 429, booster_unknown or collection_not_found. Never on a 5xx. ASCII only
  • x-decisionnode-refusal

    Example
    self_harm
    Meaning
    On a 403 refusal, and on the 200 of a refusal answered per question: the category the safety check refused
  • x-decisionnode-billable-tokens

    Example
    0
    Meaning
    Never on /v1/decide. On session answers: on a session's open, the tokens the open billed, its usage.input_tokens; 0 on every other session answer, a 403 included, and on every DELETE
  • Retry-After

    Example
    1
    Meaning
    On every 429 and 529: whole seconds to wait, rounded up. A 429 waits for the current second to end, so it is 1. A 529 is usually 1; while a model boots it is the rest of its boot window, up to 600
  • retry-after-ms

    Example
    840
    Meaning
    Beside Retry-After: the same wait in milliseconds, not rounded up to a second
  • Server-Timing

    Example
    model;dur=<ms>
    Meaning
    On every response the model's server gave, its errors included, and on cache hits: where the time went on our side, by phase, in milliseconds. Not on an error the API answers before the model. For diagnostics only; the phase names may change
Response headers
HeaderExampleMeaning
x-request-idreq_3f6c1a9e0b2d4c7f8a1e5d9bOn every response, errors included: req_ and 24 lowercase hex digits. Quote it when you contact us; store it with the decision. A request that sends its own x-request-id in that shape keeps it
x-decisionnode-request-idreq_3f6c1a9e0b2d4c7f8a1e5d9bThe same id as x-request-id, on every response
x-decisionnode-latency-ms71.0Time the model took on our side, in milliseconds with one decimal; on a cache hit, the hit's own time
x-decisionnode-modeldecisionnode-main-0.9.1-rc1The model version that answered, as in model; a fine-tuned model's pinned name
x-decisionnode-boostersage=ok:212,ai_generated=timeout:800On the answer of a request that named boosters, and on its errors once the boosters ran (booster_unavailable, a later 529, the model's errors): each booster's status and time in milliseconds, in the request's order. Not on an error raised before they run: a malformed boosters, booster_unknown, booster_not_enabled, booster_input_mismatch, key_scope_denied, a collection error, 401, 402 or 429
x-decisionnode-fallbackdecisionnode-flash-0.9.1-rc1Only on a fallback answer: the model that answered in place of DecisionNode, as in model
x-decisionnode-requested-modeldecisionnode-main-0.9.1-rc1Only on a fallback answer: the model the request asked for
x-decisionnode-cachehitOn every /v1/decide response, errors included: hit on an answer served from the cache of repeated requests; miss when the cache was looked up and held nothing; bypass when it was not looked up (the request header, zero retention, a request that cannot be cached, or an error before the lookup)
x-decisionnode-safetyharm=0.002, self_harm=0.001On every decision response, a 403 included: each category's probability, ;flagged above your key's threshold, ;blocked on a refusal, or unchecked with a reason. See Safety check
x-decisionnode-image-tokens1174When above 0: the part of usage.input_tokens that came from images
x-decisionnode-video-tokens5120When above 0: the part of usage.input_tokens that came from videos
x-decisionnode-errorquestion 'urgency': a score takes up to 10 levels, got 11What is wrong, in words, on the errors that say it: api_usage_error, the upload errors, a malformed boosters (the reason), booster_input_mismatch, a booster timeout_ms out of range, and every error the model's server sends (max_tokens_exceeded's count and limit travel here). Not on 401, 402, 403 (workspace_suspended, booster_not_enabled, key_scope_denied, collection errors), 404, 405, 408, 413, 429, booster_unknown or collection_not_found. Never on a 5xx. ASCII only
x-decisionnode-refusalself_harmOn a 403 refusal, and on the 200 of a refusal answered per question: the category the safety check refused
x-decisionnode-billable-tokens0Never on /v1/decide. On session answers: on a session's open, the tokens the open billed, its usage.input_tokens; 0 on every other session answer, a 403 included, and on every DELETE
Retry-After1On every 429 and 529: whole seconds to wait, rounded up. A 429 waits for the current second to end, so it is 1. A 529 is usually 1; while a model boots it is the rest of its boot window, up to 600
retry-after-ms840Beside Retry-After: the same wait in milliseconds, not rounded up to a second
Server-Timingmodel;dur=<ms>On every response the model's server gave, its errors included, and on cache hits: where the time went on our side, by phase, in milliseconds. Not on an error the API answers before the model. For diagnostics only; the phase names may change

Repeated requests#

The same request sent again by the same API key within 120 seconds is answered from a cache, in milliseconds, with x-decisionnode-cache: hit. Answers are deterministic, so it is the answer the model would give again. A request that looked the cache up and found nothing carries x-decisionnode-cache: miss (its answer is stored when it can be cached); one that never looked it up carries bypass. Stored answers are kept on the server that answered, so a repeat that reaches another server is computed again, and billed the same.

  • Per API key. A stored answer is only ever returned to the key that sent the request: another key, of your workspace or any other, never gets it.
  • The same request means the same model (a request naming a family is cached under its family, and a repeat names the version that answered it, so a repeat shortly after a release may carry the previous version's answer, labelled with that version; a pinned version is cached under that version alone; a plain fine-tuned name is resolved to the version that answers first), the same body byte for byte (key order and how numbers are written count, so a reformatted body is a different request), and the same x-decisionnode-safety-body and x-decisionnode-refusals headers and fallback handling.
  • Pictures are matched by their content. An inline picture is part of the body. An upload_id counts as the uploaded picture, by the SHA-256 checksum sent with the upload, so the same picture uploaded twice is the same request. An upload made without a checksum is never cached; the official SDKs always send one.
  • Never cached: a request with a url image, a request of a zero-retention workspace, any answer other than a 200, a fallback answer, an answer with a per-question refusal, a request naming the face_recognition booster, and an answer over 256 KiB. Sessions and batch lines never read or fill the cache.
  • A hit returns the stored answer byte for byte, its usage, evidence and billed_calls included, with this request's own x-request-id, except usage.cost, which is written for each answer: a hit's says what the hit booked.
  • Billed in full, exactly what the stored answer billed (its tokens and its booster calls), at the prices in force when the hit is answered, and its usage.cost says so. A hit counts against your rate limits like any request.
  • To skip the cache, send the request header x-decisionnode-cache: bypass: the answer is computed and billed, carries bypass, and is still stored for repeats when it can be cached.

Boosters#

A request may name up to 4 boosters. Each reads the request's images before the decision, within its time budget, side by side with the others; its reading is added to what the model reads and comes back in evidence. Every question is still answered by the model. One entry of results per image read, named by image:

age: Human Age (a picture of a person; 2 s; $0.024 a picture)

age_yearsinteger
The estimated age in whole years.
lowinteger
The low end of the likely range, in years.
highinteger
The high end of the likely range, in years.
confidencenumber
How sure the reading is, 0 to 1.
facesinteger
How many faces the picture shows; the largest is read. With 0 the age fields are left out.

ai_generated: AI-generated (any picture; 5 s; $0.006 a picture)

generatednumber
The probability that a generator made the picture, 0 to 1.
confidencenumber
How far the reading is from undecided, 0 to 1.
methodstring
inference when read from the pixels; c2pa when the file's trusted Content Credentials declare it generated or edited by AI, which overrides the pixels.
top_generatorobject or null
name and probability of the likeliest of the generators the booster tells apart, only when an inference reading says likely generated (generated above 0.69). Otherwise null, and always null on a c2pa reading.
c2pa_signerstring or null
Who signed the file's Content Credentials, when they are trusted; otherwise null.
c2pastring
"untrusted" when the file carries Content Credentials that validate but are not trusted; "not_checked" when the file's credentials were not checked for this request, under load or because of how the file is built, so the reading is the pixels' alone. Either way no signer and nothing changes in the reading. Absent when the file cannot carry Content Credentials.

face_detection: Face detection (any picture; 2 s; $0.001 a picture)

facesinteger
How many faces the picture shows; 0 is a reading, not a failure.
detectionsarray
One entry per face, most confident first, at most 64, and [] when there is none: its box (the corners x1, y1, x2, y2, in the request's units) and its confidence, 0 to 1.

face_recognition: Face recognition (a picture of a person; 2 s; $0.001 a picture on your own collection and $0.001 on `celebrities`)

facesinteger
How many faces in the picture were searched.
collection_namestring
Your collection's name, cut to 64 characters, on a search of your own collection only; left out when the name holds no printable text (each match's collection_name is then the col_ id). Present only on a reading from a worker on the dn-evidence-4 format.
matchesarray
One entry per face that matches, best first, at most 64, and [] when none does: its box (as Face detection's), its score, 0 to 1, the collection searched and its collection_name (your collection's name, or its col_ id when it has none; a public collection's id, such as celebrities) and the item's reference, with label for your own item that has one or name for a public figure, and metadata for your own item that carries some (on a dn-evidence-4 reading only).
options.collectionstring
A setting, in the booster object's options. Required: celebrities, the public collection, or the id of one of your workspace's face collections.
options.thresholdnumber
A setting, in the booster object's options. From 0 to 1: a face scored below it is no match. Left out, 0.5.

ocr: OCR (any picture; 12 s; $0.0015 a picture)

textstring
The reading, in the format the prompt asks for; empty when the picture shows no text.
truncatedboolean
true when the reading was too long for the request's context, so the model read it cut at its end; text stays whole.
options.promptstring
A setting, in the booster object's options. The model's instruction, at most 2,000 characters. Left out: "Text Recognition:" (all visible text, plain); "Formula Recognition:" and "Table Recognition:" are the other built-in prompts; a custom instruction or a JSON schema is allowed.

bynn_depth: Depth Vision (any picture; 800 ms; free)

aheadnumber or null
Meters to the nearest obstacle straight ahead, in the middle third of the picture, the floor or ground left out; null when none is found, such as open space or sky.
directionsarray
The same in 7 equal vertical strips of the picture, left to right: each meters or null.
groundboolean
true when a floor or ground was found and left out of ahead and directions; false when none was, and they include everything.
grid_rows, grid_colsinteger
The grid's size, grid_size by grid_size.
gridarray
The grid, row by row from the top left of the picture turned upright: each cell the median distance of its part of the picture, in meters.
depth_min, depth_max, depth_mediannumber
The nearest, the farthest and the median distance in the picture, in meters.
width, heightinteger
The picture's size in pixels, turned upright.
options.grid_sizeinteger
A setting, in the booster object's options. The grid's cells per side, from 2 to 16. Left out, 8.

bynn_segment: Segment Vision (any picture; 1.5 s; $0.001 a picture)

promptsarray
The phrases searched for, cleaned as the request's prompt is.
instancesarray
One entry per thing found, best first; [] when nothing is: its label (the phrase it matched), score, box ([x1, y1, x2, y2]), polygon (its outline), area, centroid, opening (the hole of a gate, doorway or ring, or null), depth and size_m (meters, null when depth is off). Coordinates are fractions of the picture's width and height from its top left.
depth_sourcestring or null
Where the distances come from; null when depth is off.
assumed_hfov_degnumber
The horizontal field of view the sizes in meters assume, in degrees.
width, heightinteger
The picture's size in pixels, turned upright.
options.promptstring or array
A setting, in the booster object's options. Required: what to find, one phrase as a string or 1 to 4 as an array, each at most 120 characters. A string is always one phrase (a "|" in it reads as a space), so send several as an array.
options.max_instancesinteger
A setting, in the booster object's options. At most this many found, from 1 to 16. Left out, 8.
options.min_scorenumber
A setting, in the booster object's options. A match scored below it is left out, from 0 to 1. Left out, 0.25.
options.polygon_pointsinteger
A setting, in the booster object's options. Points in each outline, from 3 to 64. Left out, 24.
options.depthboolean
A setting, in the booster object's options. Distances and sizes in meters. Left out, true.

knowledge: Knowledge (one of your knowledge bases, no picture; 800 ms; $0.001 a request)

collection, collection_namestring
The knowledge base searched: its col_ id and its name.
corpusobject
version: the knowledge base's version when it was read.
queryobject
source (auto, request or none) and tokens; text too with include_text.
budgetobject
The room the passages had: mode, tokens, entry and cause.
scopeobject or null
The scope key and the value the request named.
warningsarray
scope_not_named, over_budget, budget_floor or pinned_filtered.
passagesarray
The passages read, pinned first: n, pinned, item, reference, title, heading, chunk, byte_start and byte_end in the stored text, tokens, score (null for a pinned one) and rendered; text too with include_text.
omittedobject
Passages left out, counted by cause.
pending_itemsinteger
Documents still being processed when it was read.
searchobject
How the search ran: plan, candidates and fallback.
truncatedboolean
Always present: true when the model's context was full and passages that matched were left out.
options.collectionstring
A setting, in the booster object's options. Required: the col_ id of one of your knowledge bases.
options.scopestring
A setting, in the booster object's options. The value of the knowledge base's scope key (a mission); its items and the unscoped ones are read.
options.top_kinteger
A setting, in the booster object's options. Passages at most, pinned ones not counted, from 0 (pinned only) to 20. Left out, 4.
options.max_tokensinteger or string
A setting, in the booster object's options. The room for the passages that matched: "auto" (the default) fits them to the room the request has, up to 1,024 tokens; an integer from 128 to 8,192 gives them that room every time.
options.pinnedboolean
A setting, in the booster object's options. false leaves the pinned documents out. Left out, true.
options.matchobject
A setting, in the booster object's options. Metadata the passages must carry: a value equal, a list any of.
options.filterobject
A setting, in the booster object's options. A filter tree over the documents' metadata (and, or, conditions with eq, ne, in, nin, gt, gte, lt, lte, exists).
options.min_scorenumber
A setting, in the booster object's options. 0 to 1: a floor for passages found by meaning alone.
options.querystring
A setting, in the booster object's options. What to search with in place of the state and the questions, 1 to 2,000 characters.
options.include_textboolean
A setting, in the booster object's options. The passages' text in the answer too; a full-scope key's.

knowledge reads no image: its results hold one entry for the request, not one per image, and its call is billed once a request. Its options and citations are on Knowledge in a decision.

ocr's options.prompt is its only control: what to read and how to write it, at most 2,000 characters. The built-in task prompts give the most predictable output: "Text Recognition:", the default, plain text; "Formula Recognition:", LaTeX; "Table Recognition:", HTML or Markdown. A JSON schema in the prompt gets that JSON back in text, filled with the fields found; parse it as untrusted text. See Steering OCR with its prompt.

bynn_segment's options.prompt is required: what to find, a phrase or a list of 1 to 4 phrases of at most 120 characters, each found on its own and named again in a match's label. Its coordinates are fractions of the picture from its top left, its depth meters along the camera's axis, its size_m meters at an assumed 65-degree field of view; distances and sizes are estimates from one picture, never a safety stop. See Finding things with Segment Vision.

top_generator.name is one of the 38 generators the ai_generated booster tells apart: FLUX.1, DeepFloyd IF, Juggernaut XL, Kandinsky, Kolors, Lumina, Mobius, PixArt-alpha, Realistic Stock Photo, Stable Diffusion XL, Stable Diffusion 1.5, Stable Diffusion 2.1, Stable Diffusion 3, Stable Cascade, SSD-1B, ADM, BigGAN, GLIDE, Midjourney, VQ-Diffusion, Wukong, Nano Banana, Z-Image, GPT Image, GPT Image 2, Ideogram, Recraft, Grok Aurora, Imagen 4, Seedream, FLUX.2, Qwen-Image, DALL-E 3, Adobe Firefly, Kling, LongCat, OmniGen, Hunyuan Image. It is set only when a reading from the pixels says likely generated, generated above 0.69; a photograph reads "top_generator": null, and a c2pa reading never has one. Only trusted Content Credentials give a signer and override the pixels. Credentials that validate but are not trusted add "c2pa": "untrusted" and nothing else: no signer, no override, the reading is the pixels' own. A file whose credentials were not checked for this request, under load or because of how the file is built, adds "c2pa": "not_checked", and likewise nothing else. The five kinds of reading:

ai_generated readings
{
  "image": "c3d4",
  "generated": 0.93,
  "confidence": 0.86,
  "method": "inference",
  "top_generator": { "name": "Midjourney", "probability": 0.71 },
  "c2pa_signer": null
}
  • Rounding. Probabilities, confidences and scores in readings are rounded to 2 decimals, like answers; ages and counts are integers. A box follows the request's units: whole pixels, or fractions with 4 decimals when every point and box question asks for units: "normalized" (Boxes).
  • Time. Each booster has its own budget: 2 s for age, 5 s for ai_generated, 2 s for face_detection, 2 s for face_recognition, 12 s for ocr, 800 ms for bynn_depth, 1.5 s for bynn_segment and 800 ms for knowledge. A request may set one per booster with timeout_ms, up to the booster's ceiling. Boosters add their longest budget plus up to 2.2 s of reading the pictures, within 6 s of the request's 8 s for a request without ocr. A request naming ocr can take that much longer, so give it a client timeout of 30 s per attempt and do not retry it after a timeout (Retrying).
  • Billing. Per call billed, by booster: age (Human Age) $0.024, ai_generated (AI-generated) $0.006, face_detection (Face detection) $0.001, face_recognition (Face recognition) $0.001 on your own collection and $0.001 on celebrities, ocr (OCR) $0.0015, bynn_depth (Depth Vision) free, bynn_segment (Segment Vision) $0.001 and knowledge (Knowledge) $0.001 a request. A call is one booster reading one image with status ok, counted per booster in evidence.<name>.billed_calls and in all in usage.boosters. A reading is billed every time a request uses it, a repeat of the same picture included. A timed-out, failed or skipped booster, a picture it could not decode and a refused request bill none. See What a booster costs.
  • Where. /v1/decide and batch lines. Sessions take no boosters: boosters on a session's open is a 400.

Errors#

  • 400

    Type
    api_usage_error
    When
    An unknown model or question type, a bad image, an image id over 64 characters, a url that is not https, a url picture that changed during the request, a body nested too deep, or a malformed boosters array (not an array, over 4 entries, a name twice, an object key other than name, images, timeout_ms, require and options, a key in options, a face_recognition entry without options.collection)
    What to do
    Fix the request; the message or x-decisionnode-error names the problem
  • 400

    Type
    booster_unknown
    When
    A booster name that does not exist
    What to do
    Use age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment or knowledge
  • 400

    Type
    booster_input_mismatch
    When
    A booster on a request without images, or a booster images id that is not an image of the request
    What to do
    Add the image, or fix the id
  • 400

    Type
    image_url_refused, image_url_unreachable
    When
    An image url the fetch rules refuse (or whose media_type does not match what it holds), or one that cannot be fetched or answers other than 200. Not billed
    What to do
    Serve the picture from a public https address, or send it inline or as an upload
  • 400

    Type
    upload_not_found, upload_expired, upload_consumed, upload_media_type_mismatch, upload_incomplete, upload_mismatch
    When
    An upload_id that is unknown, past its hour, already used under zero retention, of another media type, never PUT in full, or whose bytes do not match. See Uploads
    What to do
    Upload the picture again
  • 400

    Type
    a plain string
    When
    More than 255 options or 10 levels, a choice with no options, a number question without instructions, or a truth question with neither instructions nor criteria
    What to do
    Fix that question; the string names it
  • 400

    Type
    max_tokens_exceeded
    When
    Over 64k tokens in all
    What to do
    Trim the state or split the questions; x-decisionnode-error has the count
  • 401

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

    Type
    insufficient_credit
    When
    The workspace cannot pay for the request. On a workspace with members, detail.details.reason is plan_required (no plan), trial_allowance_used (the trial's usage cap is used) or allowance_used (the month's allowance and purchased credit are used); see Plan required. On an agent workspace it is balance_empty. An allowance_used or balance_empty answer also carries WWW-Authenticate: Payment challenges an agent can pay, see Machine payments. Not billed
    What to do
    Choose or start a plan, add credit or raise the auto reload cap in the console, then retry; or retry the same call with a payment credential
  • 403

    Type
    refusal_error
    When
    Refused by the safety check; the body names the category. Not billed
    What to do
    Do not retry; change what the request asks
  • 403

    Type
    workspace_suspended
    When
    The workspace is paused, or frozen after a payment dispute. Not billed
    What to do
    Do not retry; check the console or write to hello@bynn.com
  • 403

    Type
    booster_not_enabled
    When
    A booster that is turned off for your workspace. Not billed
    What to do
    Turn it on in the console under Boosters, or leave it out
  • 408

    Type
    request_timeout_error
    When
    The body stopped arriving for 20 seconds, or took over 300
    What to do
    Retry on a working connection
  • 413

    Type
    request_too_large_error
    When
    The body is over 25 MiB (26,214,400 bytes)
    What to do
    Send large images as uploads or by URL, not inline
  • 422

    Type
    a detail list
    When
    More than 16 images or 4 videos (too_long at ["body", "images"] or ["body", "videos"]), a field is missing or has the wrong type, the body is not JSON, or a number grid cannot be built: min, max or step not a number (float_type), min above max (less_than_equal), a step of 0 or below (greater_than), min or step with more than 6 decimals (decimal_max_places), or more than 4,096 values (too_long)
    What to do
    Fix the fields listed in detail
  • 403

    Type
    key_scope_denied
    When
    A face_recognition booster on a Decisions-only key without the search allowed, or on a Publishable key: "This key may not search collections." Not billed
    What to do
    Leave the booster out, or allow the search on the key
  • 403

    Type
    origin_not_allowed, model_not_allowed
    When
    A publishable key from an origin it does not list ("This key does not answer calls from this origin."), or for a model it does not list, details.allowed naming its models. Not billed
    What to do
    Add the origin or the model to the key, or name a model it lists
  • 429

    Type
    rate_limit_error
    When
    Over your workspace's rate, or your key's own lower limit
    What to do
    Wait Retry-After, then retry
  • 429

    Type
    key_spend_cap_reached
    When
    The key has spent its daily spend cap. Not billed
    What to do
    Do not retry before the cap resets; raise the cap or use another key
  • 500

    Type
    api_error
    When
    A fault on our side, or a key that blocks a safety category whose check could not run
    What to do
    Retry with backoff; it is always safe
  • 529

    Type
    overloaded_error
    When
    No capacity right now; also a request for DecisionNode with "fallback": false (or a workspace fallback policy of never) while it has no ready capacity; and while the day's booster test calls cannot be counted (Retry-After: 2)
    What to do
    Wait Retry-After, then retry
  • 529

    Type
    booster_unavailable
    When
    A booster with require: true failed or ran out of time (booster calls that read are billed); or no server that can render the boosters' evidence is ready, whatever require says (nothing ran, nothing billed)
    What to do
    Wait Retry-After, then retry; the retry's readings are billed again
Errors this endpoint returns
StatusTypeWhenWhat to do
400api_usage_errorAn unknown model or question type, a bad image, an image id over 64 characters, a url that is not https, a url picture that changed during the request, a body nested too deep, or a malformed boosters array (not an array, over 4 entries, a name twice, an object key other than name, images, timeout_ms, require and options, a key in options, a face_recognition entry without options.collection)Fix the request; the message or x-decisionnode-error names the problem
400booster_unknownA booster name that does not existUse age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment or knowledge
400booster_input_mismatchA booster on a request without images, or a booster images id that is not an image of the requestAdd the image, or fix the id
400image_url_refused, image_url_unreachableAn image url the fetch rules refuse (or whose media_type does not match what it holds), or one that cannot be fetched or answers other than 200. Not billedServe the picture from a public https address, or send it inline or as an upload
400upload_not_found, upload_expired, upload_consumed, upload_media_type_mismatch, upload_incomplete, upload_mismatchAn upload_id that is unknown, past its hour, already used under zero retention, of another media type, never PUT in full, or whose bytes do not match. See UploadsUpload the picture again
400a plain stringMore than 255 options or 10 levels, a choice with no options, a number question without instructions, or a truth question with neither instructions nor criteriaFix that question; the string names it
400max_tokens_exceededOver 64k tokens in allTrim the state or split the questions; x-decisionnode-error has the count
401authentication_errorThe key is missing, unknown, expired or revokedCheck the Authorization header
402insufficient_creditThe workspace cannot pay for the request. On a workspace with members, detail.details.reason is plan_required (no plan), trial_allowance_used (the trial's usage cap is used) or allowance_used (the month's allowance and purchased credit are used); see Plan required. On an agent workspace it is balance_empty. An allowance_used or balance_empty answer also carries WWW-Authenticate: Payment challenges an agent can pay, see Machine payments. Not billedChoose or start a plan, add credit or raise the auto reload cap in the console, then retry; or retry the same call with a payment credential
403refusal_errorRefused by the safety check; the body names the category. Not billedDo not retry; change what the request asks
403workspace_suspendedThe workspace is paused, or frozen after a payment dispute. Not billedDo not retry; check the console or write to hello@bynn.com
403booster_not_enabledA booster that is turned off for your workspace. Not billedTurn it on in the console under Boosters, or leave it out
408request_timeout_errorThe body stopped arriving for 20 seconds, or took over 300Retry on a working connection
413request_too_large_errorThe body is over 25 MiB (26,214,400 bytes)Send large images as uploads or by URL, not inline
422a detail listMore than 16 images or 4 videos (too_long at ["body", "images"] or ["body", "videos"]), a field is missing or has the wrong type, the body is not JSON, or a number grid cannot be built: min, max or step not a number (float_type), min above max (less_than_equal), a step of 0 or below (greater_than), min or step with more than 6 decimals (decimal_max_places), or more than 4,096 values (too_long)Fix the fields listed in detail
403key_scope_deniedA face_recognition booster on a Decisions-only key without the search allowed, or on a Publishable key: "This key may not search collections." Not billedLeave the booster out, or allow the search on the key
403origin_not_allowed, model_not_allowedA publishable key from an origin it does not list ("This key does not answer calls from this origin."), or for a model it does not list, details.allowed naming its models. Not billedAdd the origin or the model to the key, or name a model it lists
429rate_limit_errorOver your workspace's rate, or your key's own lower limitWait Retry-After, then retry
429key_spend_cap_reachedThe key has spent its daily spend cap. Not billedDo not retry before the cap resets; raise the cap or use another key
500api_errorA fault on our side, or a key that blocks a safety category whose check could not runRetry with backoff; it is always safe
529overloaded_errorNo capacity right now; also a request for DecisionNode with "fallback": false (or a workspace fallback policy of never) while it has no ready capacity; and while the day's booster test calls cannot be counted (Retry-After: 2)Wait Retry-After, then retry
529booster_unavailableA booster with require: true failed or ran out of time (booster calls that read are billed); or no server that can render the boosters' evidence is ready, whatever require says (nothing ran, nothing billed)Wait Retry-After, then retry; the retry's readings are billed again

A 404 (an unknown path) and a 405 (another method than POST) are mistakes in the client. Bodies, retry rules and code are in Errors.

Limits#

  • Tokens

    Value
    64k (65,536): the state, the images and every question together
  • Questions

    Value
    No count limit; the token limit is the only bound
  • Options per choice

    Value
    1 to 255
  • Levels per score

    Value
    1 to 10
  • Values per number question

    Value
    256 as one question; finer or wider grids are composed in the same call, up to 4,096 values in all (more is a 422)
  • Images

    Value
    Up to 16 within the token limit, 10 MB and 40 megapixels each, as base64 data or an https url; resized to fit 2,048 px on the longest side
  • Videos

    Value
    Up to 4, as frames with timestamps; frame limits are listed at GET /v1/models
  • Boosters

    Value
    Up to 4, each named once; a time budget of 2 s for age, 5 s for ai_generated, 2 s for face_detection, 2 s for face_recognition, 12 s for ocr, 800 ms for bynn_depth, 1.5 s for bynn_segment and 800 ms for knowledge, and they run side by side
  • Question keys and option names

    Value
    Any string, no length limit of their own; returned byte for byte
  • Body

    Value
    25 MiB, nested at most 128 deep. Inline base64 images count toward it; images by upload_id or url do not, so send large images as uploads
  • Body arrival

    Value
    A byte at least every 20 s, the whole body within 300 s; upload time does not count toward answering
  • Rate

    Value
    Your workspace's requests and input tokens a second, shared by its keys; see Rate limits
Limits of one request
LimitValue
Tokens64k (65,536): the state, the images and every question together
QuestionsNo count limit; the token limit is the only bound
Options per choice1 to 255
Levels per score1 to 10
Values per number question256 as one question; finer or wider grids are composed in the same call, up to 4,096 values in all (more is a 422)
ImagesUp to 16 within the token limit, 10 MB and 40 megapixels each, as base64 data or an https url; resized to fit 2,048 px on the longest side
VideosUp to 4, as frames with timestamps; frame limits are listed at GET /v1/models
BoostersUp to 4, each named once; a time budget of 2 s for age, 5 s for ai_generated, 2 s for face_detection, 2 s for face_recognition, 12 s for ocr, 800 ms for bynn_depth, 1.5 s for bynn_segment and 800 ms for knowledge, and they run side by side
Question keys and option namesAny string, no length limit of their own; returned byte for byte
Body25 MiB, nested at most 128 deep. Inline base64 images count toward it; images by upload_id or url do not, so send large images as uploads
Body arrivalA byte at least every 20 s, the whole body within 300 s; upload time does not count toward answering
RateYour workspace's requests and input tokens a second, shared by its keys; see Rate limits

Notes#

  • Read answers by key. answers follows the order of your questions, and a choice's probabilities are listed alphabetically, but neither order is part of the contract.
  • Questions are independent. An answer does not depend on which other questions are in the request, so ten questions in one call answer as ten calls would, for less. One answer is never input to another: a decision that depends on an earlier answer is a second request. See How questions are answered.
  • Little evidence still gets an answer. With no state, or a state that says too little, a question gets a spread distribution with low confidence, or a truth near 0.50. It is a 200, not an error; your threshold treats it as unsure.
  • Call it from your server, or from a page with a publishable key. Any other browser is refused at the cross-origin preflight.
  • A choice always picks one of your keys, even when none fits. Add an option such as "other": "none of these" when that can happen.
  • A probability can print long. After rounding, a choice's or a score's probabilities list is nudged by 0.01 so it sums to 1, and a nudged value can print as 0.8200000000000001. Compare numbers; do not compare strings. A number answer's list is to 3 decimals and is not nudged, so over a wide grid it sums to less than 1.
  • The same request gets the same answer on the same version. See Determinism.

Deciding many times a second, or deciding a backlog?

/v1/decide answers one request with one response. For more than 10 decisions a second about the same thing, a session keeps your context loaded and streams one typed reply per frame. For a large set nothing is waiting on, a batch job runs the same requests at a lower price.

previousAPI referencenextPOST /v1/systemone

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