https://api.decisionnode.com /v1/batchesAPI=https://api.decisionnode.com/v1
curl "$API/batches" \
-H "Authorization: Bearer $DECISIONNODE_API_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @tickets.jsonlAuthentication#
AuthorizationheaderrequiredBearer dn_live_..., a Full access key: a Decisions-only key gets403key_scope_denied, "This key may only make decisions." A batch belongs to the key that created it: other keys, even in the same workspace, get404for it.Content-Typeheaderapplication/x-ndjsonfor JSON Lines,application/jsonfor an array. The API also reads the first byte:[opens an array,{a line. Not read by the API: the first byte that is not whitespace decides,[an array and{JSON Lines; a byte-order mark at the very start is skipped. AContent-Encodingother thanidentityis400api_usage_error, "Compressed uploads are not accepted."
Request body#
JSON Lines, one request per line, or a JSON array of the same objects. Each request is a /v1/decide body plus custom_id. An empty body or [] creates an empty draft you fill with Add requests.
{"custom_id":"ticket-48213","model":"decisionnode","state":"Customer: I was charged twice and nobody has replied for 3 days.","questions":{"route":{"type":"choice","instructions":"Where should this go?","criteria":{"billing":"money","bug":"broken","account":"login"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}
{"custom_id":"ticket-48214","model":"decisionnode","state":"Customer: The app crashes every time I open the invoices tab.","questions":{"route":{"type":"choice","instructions":"Where should this go?","criteria":{"billing":"money","bug":"broken","account":"login"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}
{"custom_id":"ticket-48215","model":"decisionnode","state":"Customer: My login stopped working after I changed my email address.","questions":{"route":{"type":"choice","instructions":"Where should this go?","criteria":{"billing":"money","bug":"broken","account":"login"}},"refund":{"type":"truth","instructions":"Refund this automatically?"}}}Each request
custom_idstringrequired- Your id for the request: 1 to 512 characters, unique in the batch. Its result line carries it back.
modelstringdefault"decisionnode"decisionnode,decisionnode-flashor a pinned version, and left out it isdecisionnode, exactly as on/v1/decide. It sets the line's price. One batch may mix models. An unknown name makes that line a failed line with the live400; the rest of the batch runs.statestring | object | array- The input to decide about, as on
/v1/decide. imagesarray- Images, as on
/v1/decide: base64 indata, byurl, or an upload named byupload_id. Base64 counts toward the upload size and toward the line limit, 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string; an image byurlorupload_idcounts toward neither, so send large images as uploads. Up to the model's limit of 16 a line; a DecisionNode Flash line with more than 8 can wait longer: see Lines with many images. questionsobjectrequired- The questions, as on
/v1/decide: choice, score, truth, number, point or box.
Response#
201 Created with the batch object in state draft. counters.requests counts every line; lines refused for their shape are already counted in failed.
{
"id": "batch_01J9ZB8Q3T",
"state": "draft",
"counters": {
"requests": 3,
"queued": 0,
"in_progress": 0,
"completed": 0,
"failed": 0,
"expired": 0,
"cancelled": 0
},
"created_at": "2026-10-06T09:12:04Z",
"finalized_at": null,
"expires_at": null,
"ended_at": null,
"results_url": null,
"results_expire_at": null,
"usage": { "input_tokens": 0, "output_tokens": 0 },
"error": null
}API=https://api.decisionnode.com/v1curl "$API/batches" \ -H "Authorization: Bearer $DECISIONNODE_API_KEY" \ -H "Content-Type: application/x-ndjson" \ --data-binary @tickets.jsonlErrors#
| Status | Type | When | What to do |
|---|---|---|---|
400 | api_usage_error | The upload is not usable, with one of: "The upload is neither JSON Lines nor a JSON array.", "Line {n} is not a JSON object.", "The upload is not valid UTF-8.", "Line {n} has no custom_id.", "Line {n}: custom_id must be a string of 1 to 512 characters.", "Line {n}: custom_id {id} is already in the batch.", "The batch would hold {count} requests. The limit is 10000."; or a compressed body, "Compressed uploads are not accepted." | Fix the upload and send it again. Nothing was created |
401 | authentication_error | The key is missing, unknown or revoked | Check the Authorization header |
402 | insufficient_credit | The workspace cannot pay: details.reason plan_required, trial_allowance_used or allowance_used on a workspace with members, balance_empty on an agent workspace (Plan required) | Add credit or fix the plan in the console, then call again |
403 | key_scope_denied | A Decisions-only key: "This key may only make decisions." Checked before the rate | Use a Full access key on your server |
403 | workspace_suspended | The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com." | Write to us |
408 | request_timeout_error | "The request body did not arrive in time." No byte for 20 s, the body not complete after 1,800 s, or, after the first MiB, under 64 KiB a second over any 60 s | Send it again on a faster connection, or in parts with add calls |
413 | request_too_large_error | The upload is over 256 MiB ("The request body is over the size limit."), one line is over 25 MiB ("Line {n} is over 25 MiB."), or one line is over 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, an inline image's base64 included ("Line {n} is over 17767680 bytes as a batch job (its quotes and backslashes counted twice). Send large images as uploads (POST /v1/uploads) and name them by upload_id."); nothing is applied | Split it into several batches of up to 10,000 requests; send large images with POST /v1/uploads and name them by upload_id |
429 | batch_limit_exceeded | Your key already has 10 active batches ("This key already has 10 active batches."), or your workspace 50 ("This workspace already has 50 active batches."); Retry-After: 30 | Finalize or cancel a draft, or wait for a batch to end |
429 | batch_limit_exceeded | The call would put more than 100,000 requests in your key's active batches, drafts included ("This call would put {n} requests in this key's active batches. The limit is 100000."), or more than 500,000 in your workspace's, or make your workspace's batches store more than 20.0 GiB (uploads, and results not yet deleted; checked before the body is read). Retry-After: 30 | Wait for a batch to end, or cancel a draft you will not finalize. Nothing from the call was applied |
429 | rate_limit_error | Uploads in progress: "This key already has 2 uploads in progress." or "This workspace already has 4 uploads in progress.", Retry-After: 30 | Wait for an upload to finish |
429 | rate_limit_error | Over your workspace's request rate (or your key's own lower limit): batch calls count against it | Wait Retry-After seconds, then send the same call again |
500 | api_error | A fault on our side | Retry with backoff and jitter. A 5xx can come after the call took effect: before you create again, cancel any draft the failed create left behind (see Batch errors) |
529 | overloaded_error | The service's upload memory or its store of batches is full right now | Wait Retry-After seconds, then retry |
529 | overloaded_error | The API cannot take the call right now | Wait Retry-After seconds, then retry with backoff |
Every error body is {"detail": {"error_type": "...", "message": "..."}}. Retry 408, 429 (rate_limit_error), 529 and any 5xx, waiting at least what Retry-After says when it is set; fix the call for the other 4xx. A 429 batch_limit_exceeded clears only when a batch ends or you cancel one. All the bodies are on Errors.
Limits#
| Limit | Value |
|---|---|
| Requests | Up to 10,000 |
| Upload | 256 MiB, images included |
| One line | 25 MiB as sent, and in effect 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, which is how a batch job carries the line: each ", \, tab and newline counts twice. An inline image's base64 counts toward it; an image by url or upload_id does not |
custom_id | 1 to 512 characters, unique in the batch |
| Each request | The live limits of /v1/decide |
| Requests in active batches per key | 100,000, drafts included, checked on this call |
Notes#
- A line the API refuses for its shape (an unknown model, a question with no options, a field of the wrong type, a point or box question asking for
max, which is the422not_supported) is accepted into the batch as a failed line with the live status and body and anx-decisionnode-errorheader naming the refusal, and never runs. The rest of the batch is unaffected. - Limits counted in tokens, such as the per-request token limit, are checked when the line runs: such a line comes back as the live
400. - A refused upload leaves nothing behind: no draft, no lines.
- The draft counts toward your 10 active batches until you finalize or cancel it; a draft not finalized within 24 hours of
created_atis cancelled.