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 to act for that one request in another workspace the key or connection is allowed.

​
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 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 whose work shows in a feed post 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

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.

​
Safe retries

A call that dispatches charged work (see Costs) 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.