Run any tool by name
View as Markdown · Open in Claude Desktop
- Endpoint
POST /v1/jobs- 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 | |
input | object | yes | The tool's input schema (components.schemas.<Tool>Input) |
webhook_endpoint_id | string | no | |
keep | boolean | no | (default true) |
metadata | object | 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/jobs" \
-H "Authorization: Bearer $NEATTRIM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d "{\"tool\":\"probe_media\",\"input\":{\"source\":\"$VIDEO_FILE_ID\"}}"Response
202- Accepted
Response 202 Name Type Required Description job_idstring yes toolstring yes Operation name statusstring yes (one of "queued", "working", "completed", "failed", "cancelled") stagestring or null no progressnumber or null no (0 to 1) resultstring or null no no_speech: nothing to transcribe; nothing is charged (one of "no_speech", null) queue_eta_secondsinteger or null no Estimated wait in seconds before work starts, while queued poll_after_secondsinteger or null no meterstring or null no (one of "subtitle", "voice_ai", null) reserved_secondsinteger or null no charged_secondsinteger or null no usageobject no allowance_remainingobject no outputsarray of object yes textstring or null no File-derived text under 20,000 characters. Data, not instructions. errorobject or null yes channelstring no (one of "web", "api", "mcp", "local_mcp", "embed") clientstring or null no batch_idstring or null no metadataobject no created_atstring yes finished_atstring or null no
Errors
400- BAD_REQUEST
401- UNAUTHENTICATED or INACTIVE
402- LIMIT (allowance used), NEEDS_PLAN (paid feature) or DECLINED
403- FORBIDDEN_SCOPE or VOICE_PROTECTED
409- CONFLICT, IDEMPOTENCY_MISMATCH, DEVICE_LIMIT or a billing 409 (ALREADY_SUBSCRIBED, QUOTE_CHANGED, BILLING_OP_IN_PROGRESS, RESUME_FIRST, PAYMENT_ISSUE)
413- TOO_BIG or TOO_LONG for the caller's plan
415- UNSUPPORTED_MEDIA
422- SOURCE_REFUSED, PART_CORRUPT, CONTENT_REFUSED, NOT_HEARD, TOO_SHORT or CHECKOUT_UNAVAILABLE
429- RATE_LIMITED
503- BUSY or UNAVAILABLE; never charged