POST
https://api.decisionnode.com /v1/batches/{id}/requestsAPI=https://api.decisionnode.com/v1
BATCH=batch_01J9ZB8Q3T
curl "$API/batches/$BATCH/requests" \
-H "Authorization: Bearer $DECISIONNODE_API_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @more.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-ndjsonorapplication/json, as on create. 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."
Path parameters#
idstringrequired- The batch id that Create a batch returned, for example
batch_01J9ZB8Q3T.
Request body#
The same format as Create a batch: JSON Lines or a JSON array of requests, each with a custom_id unique across the whole batch, not only this call.
Response#
200 OK with the batch object, still a draft, its counters including the new lines.
{
"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/v1BATCH=batch_01J9ZB8Q3Tcurl "$API/batches/$BATCH/requests" \ -H "Authorization: Bearer $DECISIONNODE_API_KEY" \ -H "Content-Type: application/x-ndjson" \ --data-binary @more.jsonlErrors#
| Status | Type | When | What to do |
|---|---|---|---|
400 | api_usage_error | The body cannot be read (the messages of create); a custom_id is missing, too long or already in the batch; the batch would pass 10,000 requests; an empty body or [], "The call holds no requests." | Fix the call and send it again. Nothing from it was added |
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 |
404 | not_found_error | No batch with this id belongs to your key | Check the id and that you call with the key that created the batch |
408 | request_timeout_error | "The request body did not arrive in time." No byte for 20 s, or the body not complete after 300 s | Send it again |
409 | invalid_batch_state | The batch is no longer a draft: it was finalized or cancelled | Create a new batch for more requests |
413 | request_too_large_error | The call is over 10 MiB, one line is over 25 MiB or over 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string (the messages of create), or the batch would pass 256 MiB ("The batch would pass its size limit of 256 MiB.") | Send smaller calls, or start a second batch; send large images with POST /v1/uploads and name them by upload_id |
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 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 |
|---|---|
| One call | 10 MiB |
| One line | Inside the call, and at most 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string; an inline image's base64 counts toward it |
| The batch | 10,000 requests and 256 MiB in all |
| Requests in active batches per key | 100,000, drafts included, checked on this call |
Notes#
- A call is all or nothing: if it is refused, none of its lines were added, so you can resend it whole.
- If a call times out, retrieve the batch and compare
counters.requestswith what you sent before you resend: acustom_idalready in the batch is refused, which keeps a resent call from adding lines twice.