Skip to main content
An Action is a typed capability with a JSON Schema for its input and its output: generate an image, render HTML to PDF, create a GitHub issue, search a CRM, transform a file. Agents reach the catalog through a small set of meta-tools; your own code reaches the same catalog over HTTP, and both produce the same run records. Actions span image, video, audio, 3D, document, file, web, data, and integration categories. New ones appear in the catalog without an API change on your side, which is the point of a registry rather than an endpoint per capability.

​
Find an Action

Ids read as category_verb - image_generate, file_write, html_to_pdf. If you guess generate_image and get a 404, the error suggests the right id. Fetch one Action’s schemas on their own:

​
Run one

Fast Actions return output in the response. Long-running ones return queued or running with a runId to poll:
Run status is one of queued, running, succeeded, failed, or canceled. A run record also carries progress while it is in flight and error when it fails. To follow a run without polling, read its status stream. Every data: frame is the same JSON the run endpoint returns, sent when it changes, and the stream ends with an event: end frame once the run is over:
If the connection drops, reconnect with ?cursor=<last id> (the last id: line you received) to resume without replaying history. Imports, media generation jobs, site builds and workspace copies expose the same /events shape beside their status endpoints.

​
Repeating a call safely

Pass idempotencyKey and a repeated call returns the original run instead of doing the work twice. Worth doing for anything that costs money or writes a file, since retries are the normal shape of a scheduled job.

​
Actions that write require write access

An Action’s declared permission decides what it needs: read-only Actions need workspace read, anything that writes needs workspace write. A credential without it gets 403 before the Action runs.

​
Run several at once

A dashboard that renders from a dozen independent reads should not pay a dozen round trips. Send them as one batch of up to 50 calls:
A batch is not a transaction. Every call reports its own outcome and the response is 200 even when some fail:
Results line up positionally with the calls you sent. An unknown actionId fails the whole request with a 404 rather than half-running the batch.

​
Fields whose options depend on other fields

Some inputs cannot be enumerated up front - the folders in a connected Drive account, the models available for an image Action. Resolve those at call time:

​
Reviewing what ran

Runs record which Action ran, its status, its output, and its cost, whoever started it - an agent turn, an automation, the product UI, or your own call. That makes the run list the single place to answer “what did this workspace actually do”.

​
How agents use the same catalog

Agents do not carry a tool per Action. They get four meta-tools - search, describe, run, and list runs - and pull a schema only when they need it. So an Action you can call over HTTP is one an agent in the same workspace can already use, with no registration step and no prompt changes. To let an agent use an Action you have already scripted, just tell it what you want in plain language; it will find the id itself.