https://api.decisionnode.com /v1/decidecurl 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#
AuthorizationstringrequiredBearer dn_live_.... Keep keys on your server and read them from an environment variable such asDECISIONNODE_API_KEY. The API refuses calls from browsers, exceptPOST /v1/decidewith a publishable key from an origin it lists: a cross-origin preflight for any other route these docs describe gets400Disallowed CORS origin, so a frontend calls your backend and your backend calls DecisionNode.Content-Typestringapplication/json. Not checked: the body is read as JSON whatever its type.x-decisionnode-safety-bodystringdefaultofftrue,1oryesadds a top-levelsafetyobject to a200body: what the safety check found, to four decimals. Without it the body holds onlymodel,answersandusage.x-decisionnode-cachestringbypassskips the cache of repeated requests: the answer is computed and billed, carriesbypass, and is still stored for repeats when it can be cached.
Request body#
modelstringdefault"decisionnode"decisionnodeordecisionnode-flash, a pinned version such asdecisionnode-main-0.9.1-rc1, or a fine-tuned model of your workspace:<base>@<workspace>/<name>, such asdecisionnode-flash@acme/, withfraud :<version>to pin one. Any other name, a fine-tuned version that is not deployed and another workspace's model included, is a400Unknown model. See Versions.fallbackbooleandefaulttrue- What happens when DecisionNode has no ready capacity.
true: a request fordecisionnode(the family, or an earlier alias of it) is answered at once bydecisionnode-flash-0.9.1-rc1, billed at DecisionNode Flash's price, and says so:modelnames DecisionNode Flash, and thex-decisionnode-fallbackandx-decisionnode-requested-modelheaders name both models.false: the request gets529overloaded_errorwithRetry-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 isneveris always answered asfalse. 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 the529it 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.
nulland[]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 ("Doesclaim_photoshow 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 ofdata,urlandupload_id. urlstring- An
httpsaddress the server fetches the image from, at most 2,048 characters. Send one ofdata,urlandupload_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 ofdata,urlandupload_id. media_typestringimage/jpeg,image/pngorimage/webp. Required withdata; optional withurlandupload_id, where it must match the image when given.
videosarraydefault[]- Up to 4 videos, each sent as frames with their timestamps (
id,frames, optionalfps,startandend), read as one video with order and timing and seen by every question. Questions refer to a video by itsidor 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.nulland[]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 oncelebrities,ocr(OCR) $0.0015,bynn_depth(Depth Vision) free,bynn_segment(Segment Vision) $0.001 andknowledge(Knowledge) $0.001 a request.namestringrequired- The booster's name:
age,ai_generated,face_detection,face_recognition,ocr,bynn_depth,bynn_segmentorknowledge. Another name is a400booster_unknown. imagesarraydefaultevery image- The
ids of the images it reads. An id that is not an image of the request is a400booster_input_mismatch. timeout_msintegerdefaultthe booster's budget- Its time budget for this request, in milliseconds, from 100 to the booster's ceiling (
max_deadline_msin the catalogue; the defaults and ceilings: 2 s up to 5 s forage, 5 s up to 6 s forai_generated, 2 s up to 5 s forface_detection, 2 s up to 5 s forface_recognition, 12 s up to 12 s forocr, 800 ms up to 5 s forbynn_depth, 1.5 s up to 5 s forbynn_segmentand 800 ms up to 5 s forknowledge). Outside that range or not an integer is a422at["body", "boosters", <i>, "timeout_ms"](int_type,greater_than_equal,less_than_equal), and nothing runs. On the OpenAI-compatible route, the400withparamboosters[<i>].timeout_ms. requirebooleandefaultfalsetrue: a booster that fails or runs out of time fails the request with529booster_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
400api_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 a400, "Number question must have instructions: <key>". A truth question needsinstructionsorcriteria: with neither, it is a400. 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 inlegendas sent. Truth: optional{"true": "...", "false": "..."}, what true and what false mean;nulland{}mean no criteria. Number: not used, the grid is the set of answers. minnumberdefault0- Number only: the lowest value.
maxnumberdefault255- Number only: the highest value, at least
min. stepnumberdefault1- Number only: the grid spacing, above 0, such as
0.5for halves or0.1for 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
idof 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:
pixelsof the image as sent, ornormalizedfractions 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#
{
"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 asdecisionnode-flash@acme/. On a fallback answer it isfraud:3 decisionnode-flash-0.9.1-rc1, the model that answered, not the one you asked for. answersobject- One answer per question key.
choice answerobjecttype,choice(one of your keys),confidence,probabilities(alphabetical by key).score answerobjecttype,score(expected level index),confidence,legend,probabilities(in level order).truth answerobjecttype("truth") andtruth, the probability that the statement is true, from 0.00 to 1.00.number answerobjecttype,number(the most probable grid value, written as your grid writes it:7on a whole-number grid,3.5on a grid of 0.5),expected(the probability-weighted mean, a float such as7.3or7.0),confidence(the probability ofnumber),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). Readnumberas a float in a typed client; it always equals a value of your grid.point answerobjecttype,xandy(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 onpresent),image,widthandheight. See Points and boxes.box answerobjecttype,x1,y1(top-left) andx2,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 onpresent),image,widthandheight.
usageobjectinput_tokensbilled for this request, andoutput_tokens, which is always 0. A request with videos also getsvideo_framesandvideo_seconds. A request that named boosters also getsbooster_tokens, the part ofinput_tokensthe readings take, andboosters, 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_usdplusboosters_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_tierbooleantrueonly when a daily free count covered the model's request. Workspaces have no free daily counts, so it isfalse; 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 asage-v3. statusstringok,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'sbilled_callstimes that booster's price;usage.boostersis the total. resultsarray- One entry per picture, named by
image. Onok, each carries the booster's fields below, or"readable": falsefor a picture it could not decode (not billed). Ontimeoutorerror, one bare{"image": id}per picture it was meant to read, andbilled_callsis 0. Onskipped, empty.
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#
| Header | Example | Meaning |
|---|---|---|
x-request-id | req_3f6c1a9e0b2d4c7f8a1e5d9b | 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 | req_3f6c1a9e0b2d4c7f8a1e5d9b | The same id as x-request-id, on every response |
x-decisionnode-latency-ms | 71.0 | Time the model took on our side, in milliseconds with one decimal; on a cache hit, the hit's own time |
x-decisionnode-model | decisionnode-main-0.9.1-rc1 | The model version that answered, as in model; a fine-tuned model's pinned name |
x-decisionnode-boosters | age=ok:212,ai_generated=timeout:800 | 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 | decisionnode-flash-0.9.1-rc1 | Only on a fallback answer: the model that answered in place of DecisionNode, as in model |
x-decisionnode-requested-model | decisionnode-main-0.9.1-rc1 | Only on a fallback answer: the model the request asked for |
x-decisionnode-cache | hit | 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 | harm=0.002, self_harm=0.001 | 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 | 1174 | When above 0: the part of usage.input_tokens that came from images |
x-decisionnode-video-tokens | 5120 | When above 0: the part of usage.input_tokens that came from videos |
x-decisionnode-error | question 'urgency': a score takes up to 10 levels, got 11 | 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 | self_harm | On a 403 refusal, and on the 200 of a refusal answered per question: the category the safety check refused |
x-decisionnode-billable-tokens | 0 | 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 | 1 | 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 | 840 | Beside Retry-After: the same wait in milliseconds, not rounded up to a second |
Server-Timing | model;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-bodyandx-decisionnode-refusalsheaders and fallback handling. - Pictures are matched by their content. An inline picture is part of the body. An
upload_idcounts 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
urlimage, a request of a zero-retention workspace, any answer other than a200, a fallback answer, an answer with a per-question refusal, a request naming theface_recognitionbooster, 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,evidenceandbilled_callsincluded, with this request's ownx-request-id, exceptusage.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.costsays 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, carriesbypass, 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.
methodstringinferencewhen read from the pixels;c2pawhen the file's trusted Content Credentials declare it generated or edited by AI, which overrides the pixels.top_generatorobject or nullnameandprobabilityof the likeliest of the generators the booster tells apart, only when aninferencereading says likely generated (generatedabove 0.69). Otherwisenull, and alwaysnullon ac2pareading.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: itsbox(the cornersx1,y1,x2,y2, in the request's units) and itsconfidence, 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_nameis then thecol_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: itsbox(as Face detection's), itsscore, 0 to 1, thecollectionsearched and itscollection_name(your collection's name, or itscol_id when it has none; a public collection's id, such ascelebrities) and the item'sreference, withlabelfor your own item that has one ornamefor a public figure, andmetadatafor 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.
truncatedbooleantruewhen the reading was too long for the request's context, so the model read it cut at its end;textstays 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;
nullwhen 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. groundbooleantruewhen a floor or ground was found and left out ofaheadanddirections;falsewhen none was, and they include everything.grid_rows, grid_colsinteger- The grid's size,
grid_sizebygrid_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
promptis. instancesarray- One entry per thing found, best first;
[]when nothing is: itslabel(the phrase it matched),score,box([x1, y1, x2, y2]),polygon(its outline),area,centroid,opening(the hole of a gate, doorway or ring, ornull),depthandsize_m(meters,nullwhen 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;
nullwhen 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. corpusobjectversion: the knowledge base's version when it was read.queryobjectsource(auto,requestornone) andtokens;texttoo withinclude_text.budgetobject- The room the passages had:
mode,tokens,entryandcause. scopeobject or null- The scope key and the value the request named.
warningsarrayscope_not_named,over_budget,budget_floororpinned_filtered.passagesarray- The passages read, pinned first:
n,pinned,item,reference,title,heading,chunk,byte_startandbyte_endin the stored text,tokens,score(null for a pinned one) andrendered;texttoo withinclude_text. omittedobject- Passages left out, counted by cause.
pending_itemsinteger- Documents still being processed when it was read.
searchobject- How the search ran:
plan,candidatesandfallback. truncatedboolean- Always present:
truewhen the model's context was full and passages that matched were left out. options.collectionstring- A setting, in the booster object's
options. Required: thecol_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.falseleaves 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 witheq,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:
{
"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
boxfollows the request's units: whole pixels, or fractions with 4 decimals when every point and box question asks forunits: "normalized"(Boxes). - Time. Each booster has its own budget: 2 s for
age, 5 s forai_generated, 2 s forface_detection, 2 s forface_recognition, 12 s forocr, 800 ms forbynn_depth, 1.5 s forbynn_segmentand 800 ms forknowledge. A request may set one per booster withtimeout_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 withoutocr. A request namingocrcan 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 oncelebrities,ocr(OCR) $0.0015,bynn_depth(Depth Vision) free,bynn_segment(Segment Vision) $0.001 andknowledge(Knowledge) $0.001 a request. A call is one booster reading one image with statusok, counted per booster inevidence.<name>.billed_callsand in all inusage.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/decideand batch lines. Sessions take no boosters:boosterson a session's open is a400.
Errors#
| Status | Type | When | What to do |
|---|---|---|---|
400 | api_usage_error | 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) | Fix the request; the message or x-decisionnode-error names the problem |
400 | booster_unknown | A booster name that does not exist | Use age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment or knowledge |
400 | booster_input_mismatch | A booster on a request without images, or a booster images id that is not an image of the request | Add the image, or fix the id |
400 | image_url_refused, image_url_unreachable | 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 | Serve the picture from a public https address, or send it inline or as an upload |
400 | upload_not_found, upload_expired, upload_consumed, upload_media_type_mismatch, upload_incomplete, upload_mismatch | 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 | Upload the picture again |
400 | a plain string | 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 | Fix that question; the string names it |
400 | max_tokens_exceeded | Over 64k tokens in all | Trim the state or split the questions; x-decisionnode-error has the count |
401 | authentication_error | The key is missing, unknown, expired or revoked | Check the Authorization header |
402 | insufficient_credit | 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 | 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 | refusal_error | Refused by the safety check; the body names the category. Not billed | Do not retry; change what the request asks |
403 | workspace_suspended | The workspace is paused, or frozen after a payment dispute. Not billed | Do not retry; check the console or write to hello@bynn.com |
403 | booster_not_enabled | A booster that is turned off for your workspace. Not billed | Turn it on in the console under Boosters, or leave it out |
408 | request_timeout_error | The body stopped arriving for 20 seconds, or took over 300 | Retry on a working connection |
413 | request_too_large_error | The body is over 25 MiB (26,214,400 bytes) | Send large images as uploads or by URL, not inline |
422 | a detail list | 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) | Fix the fields listed in detail |
403 | key_scope_denied | 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 | Leave the booster out, or allow the search on the key |
403 | origin_not_allowed, model_not_allowed | 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 | Add the origin or the model to the key, or name a model it lists |
429 | rate_limit_error | Over your workspace's rate, or your key's own lower limit | Wait Retry-After, then retry |
429 | key_spend_cap_reached | The key has spent its daily spend cap. Not billed | Do not retry before the cap resets; raise the cap or use another key |
500 | api_error | A fault on our side, or a key that blocks a safety category whose check could not run | Retry with backoff; it is always safe |
529 | overloaded_error | 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) | Wait Retry-After, then retry |
529 | booster_unavailable | 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) | 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#
| Limit | Value |
|---|---|
| Tokens | 64k (65,536): the state, the images and every question together |
| Questions | No count limit; the token limit is the only bound |
| Options per choice | 1 to 255 |
| Levels per score | 1 to 10 |
| Values per number question | 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 | 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 | Up to 4, as frames with timestamps; frame limits are listed at GET /v1/models |
| Boosters | 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 | Any string, no length limit of their own; returned byte for byte |
| Body | 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 | A byte at least every 20 s, the whole body within 300 s; upload time does not count toward answering |
| Rate | Your workspace's requests and input tokens a second, shared by its keys; see Rate limits |
Notes#
- Read answers by key.
answersfollows the order of your questions, and a choice'sprobabilitiesare 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
probabilitieslist is nudged by 0.01 so it sums to 1, and a nudged value can print as0.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.