Calling tools

Request

POST /api/v1/tools/{name} with the tool’s input as the JSON body. A read tool also answers GET with its input as query parameters, each converted to the type the schema declares; a read of many ids is a POST. Unknown fields and wrong types are rejected before anything runs. Two headers apply to any tool: Idempotency-Key, equivalent to the idempotency_key field on a charged call, and x-workspace-id for an OAuth token naming another workspace.

Response

{
  "ok": true,
  "data": { … },
  "meta": { "request_id": "req_…", "cost": { … }, "cloud_processing": { … } },
  "media": [ … ]
}

meta.cost is present when credits were charged and meta.cloud_processing when minutes were, each with what was charged and what is left. media carries the pictures a tool returned inline (frames, a rendered still), so a REST caller sees what an MCP client sees.

Response types

What data holds depends on the tool’s kind, and every tool’s description says what it returns.

A result, from any write: what changed and the resulting state, with the ids of what was created. Reading the object again after a write returns what the response already said. A timeline or canvas write carries the new revision, and a write posted to the feed carries feed_url.
A job, from any slow operation: its id, place in the queue and estimate. get_jobs follows it. See Jobs.
A page, from any list: rows and next_cursor, passed back with the same filters for the next page. A read that stopped early says so in cut_short.
A batch, from a tool that takes many refs: one result per input. A failed input is reported beside the rest rather than failing the call.

Errors

{
  "ok": false,
  "error": { "code": "…", "message": "…", "retryable": false, "suggested_action": "…" }
}

suggested_action is the next call that works, not a restatement of the error. Work that used minutes before failing carries cloud_processing on the error.

Code	Status	Retry	Meaning and next step
`validation_error`	400	no	The message names the field. `GET /tools` carries the exact input schema.
`not_media`	400	no	The ref is not audio or video.
`unauthorized`	401	no	The credential is missing or invalid.
`forbidden`	403	no	The credential has no access to this resource. Another id will not help.
`refused`	403	no	Declined on purpose. The message says why.
`not_found`	404	no	Re-read the object that gave you the id rather than assembling one.
`insufficient_credits`	402	no	`get_balance` returns the balance and where more can be added.
`storage_full`	507	no	The owner’s storage has no room for what this makes. `get_checkout_link` with `product: "storage"` returns a link to buy more, or `delete_items` frees room.
`conflict`	409	no	Something changed underneath. Re-read and reapply.
`revision_conflict`	409	no	The document moved since the revision given, or a user edited it since the last read. Re-read and reapply.
`needs_cloud`	409	no	The call, made through the desktop app, set `run_on: "local"` and the work needed the cloud, so it did not run. Call again without it, or with `run_on: "cloud"`.
`rate_limited`	429	yes	Wait for `Retry-After`, then retry the same call with the same key.
`payload_too_large`	413	no	The body is over 9 MB. Send the file by upload or URL instead.
`unavailable`	503	yes	A provider or the service is briefly unavailable. Wait for `Retry-After`, then retry with the same key.
`internal_error`	500	once	An error on our side, not in the call. If it repeats, `submit_feedback`.

Safe retries

A call that charges takes an idempotency_key, generated for that operation. The same key on a retry, in the field or in the Idempotency-Key header, returns the job already dispatched instead of charging again. A new attempt takes a new key. A write to a timeline or canvas takes if_revision from the last read. See Timelines and canvases.

Timing

A call answers within about 30 seconds or returns a job. The API allows a call up to 300 seconds for the slowest tools. A client that cuts a call earlier loses the answer, not the work.

Get started

Concepts

Build on the API

Trust

Request

Response

Response types

Errors

Safe retries

Timing

​Request

​Response

​Response types

​Errors

​Safe retries

​Timing

Request

Response

Response types

Errors

Safe retries

Timing