Base URL
*) so you can call the API from any origin, including browsers.
Endpoints
POST /api/v1/responses
Start a workflow run. Stream results over SSE, or get a
run_id back and poll asynchronously.GET /api/v1/runs/{runId}
Fetch the status and output of a run. Safe to poll.
GET /api/v1/runs/{runId}/stream
Reconnect to an in-flight run’s SSE stream, or attach to a fire-and-forget run.
Two execution modes
Every workflow run operates in one of two modes, controlled by thestream field on POST /responses:
Async mode is the common choice for server-to-server integration. Streaming mode is what you want when a user is watching progress in real time.
Request shape
Every call to/responses follows the same shape:
inputs are the normalized labels of the User Input nodes in your workflow — “Reference Image” becomes reference_image, “Prompt” becomes prompt.
Only User Input nodes become API inputs. Ordinary node fields, Batch rows, and internal tool/model settings stay inside the workflow unless you expose them with a User Input.
Response shape
Async mode returns:GET /runs/{run_id} until status is completed, then read the output object. Each key corresponds to a User Result node in your workflow. Each value is an array of output items, and each item contains typed parts — see Output Parts for the full shape.
Explore the reference
Authentication
API keys, rate limits, and headers.
Streaming
SSE event types and how to handle them.
Errors
Status codes, error types, and sub-codes.
Output Parts
How to read output items and
text, image, video, file, and json parts.