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
Whatdata 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_jobsfollows 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 incut_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 anidempotency_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.

