Skip to main content

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, which runs that one request in another workspace the key or connection is allowed to use.

Response

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 includes 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 returns what the response already says. A timeline or canvas write includes the new revision, and a write whose work shows in a feed post includes 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, which returns the next page when sent back with the same filters. 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 alongside the others instead of failing the whole call.

Errors

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

Safe retries

A call that starts charged work (see Costs) accepts an idempotency_key, made for that operation. A retry with the same key, in the field or in the Idempotency-Key header, returns the job already started instead of charging again. A new attempt uses a new key. A write to a timeline or canvas accepts 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. If a client cuts a call off earlier, the answer is lost but the work continues.