Run one tool over many inputs (every account, within its allowance)
View as Markdown · Open in Claude Desktop
- Endpoint
POST /v1/batches- Who can call it
- An API key, or an OAuth token for an app.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Required on POSTs that create a job, upload, checkout, plan change or top-up; stored 24 h per ledger subject; same key with a different body returns 409 IDEMPOTENCY_MISMATCH |
Neattrim-Simulate | header | string | no | Test keys only (km_test_). Forces a deterministic outcome such as completed, failed or LIMIT for sandbox tests; ignored with live keys |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
tool | any | yes | |
settings | object | no | |
inputs | array of object | yes | |
webhook_endpoint_id | string | no |
Examples
Set NEATTRIM_API_KEY to your key, then copy an example. A tool that draws from your allowance reads an uploaded file: upload a sample file as in the quickstart and set VIDEO_FILE_ID (or AUDIO_FILE_ID, IMAGE_FILE_ID, SUBTITLES_FILE_ID) to its file_id. Any other id in an example, such as JOB_ID, is read from a variable of the same name.
curl -X POST "https://api.neattrim.com/v1/batches" \
-H "Authorization: Bearer $NEATTRIM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d "{\"tool\":\"probe_media\",\"inputs\":[{\"source\":\"$VIDEO_FILE_ID\"},{\"source\":\"$AUDIO_FILE_ID\"}]}"Response
202- Batch
Response 202 Name Type Required Description batch_idstring yes toolstring no statusany yes (one of "queued", "working", "completed", "cancelled") itemsarray of object yes usageany no zip_urlstring or null no
Errors
400- BAD_REQUEST
401- UNAUTHENTICATED or INACTIVE
402- LIMIT (allowance used), NEEDS_PLAN (paid feature) or DECLINED
413- TOO_BIG or TOO_LONG for the caller's plan
422- SOURCE_REFUSED, PART_CORRUPT, CONTENT_REFUSED, NOT_HEARD, TOO_SHORT or CHECKOUT_UNAVAILABLE
429- RATE_LIMITED