Appearance
Workflows
Create, version, and run multi-agent DAG workflows. Workflows chain agents from the Agent Library into automated runs with branching, parallel fan-out/in, loops, and error routing.
List workflows
GET
/v1/workflows
List the workflow summaries visible to the caller. Pass mine=true to narrow that to only what the caller created. Community workflows are listed by GET /workflows/community.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
page
Type
integer
Default
1Minimum
1page_size
Type
integer
Default
20Maximum
100Minimum
1sort
Type
string
Default
"updated_at"Pattern
"^(name|created_at|updated_at|run_count)$"order
Type
string
Default
"desc"Pattern
"^(asc|desc)$"search
mine
Type
boolean
Default
falseResponses
Successful Response
application/json
JSON "items": [ { "active_version_id": "string", "active_version_number": 0, "agent_names": [ [ ] ], "can_write": true, "connector_providers": [ [ ] ], "created_at": "string", "created_by": "string", "created_by_name": "string", "cron_expression": "string", "cron_timezone": "string", "delist_listing_id": "string", "description": "string", "graph_shape": { "edges": [ [ ] ], "nodes": [ { "type": "string" } ] }, "icon_name": "string", "id": "string", "last_run_at": "string", "listing_source_id": "string", "name": "string", "node_count": 0, "org_name": "string", "pinned": false, "run_count": 0, "source_draft_id": "string", "team_ids": [ "string" ], "trigger_kinds": [ [ ] ], "updated_at": "string", "visibility": "string" } ], "next_cursor": "string", "page": 0, "page_size": 0, "total": 0
{
}
Samples
List community workflows
GET
/v1/workflows/community
Every org's published workflows, unscoped, newest first. A community workflow is readable and importable but cannot be run, edited or bound into a definition.
The shelf is paged: follow next_cursor until it is null.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
search
cursor
next_cursor from the previous page.
Responses
Successful Response
application/json
JSON "items": [ { "active_version_id": "string", "active_version_number": 0, "agent_names": [ [ ] ], "can_write": true, "connector_providers": [ [ ] ], "created_at": "string", "created_by": "string", "created_by_name": "string", "cron_expression": "string", "cron_timezone": "string", "delist_listing_id": "string", "description": "string", "graph_shape": { "edges": [ [ ] ], "nodes": [ { "type": "string" } ] }, "icon_name": "string", "id": "string", "last_run_at": "string", "listing_source_id": "string", "name": "string", "node_count": 0, "org_name": "string", "pinned": false, "run_count": 0, "source_draft_id": "string", "team_ids": [ "string" ], "trigger_kinds": [ [ ] ], "updated_at": "string", "visibility": "string" } ], "next_cursor": "string", "page": 0, "page_size": 0, "total": 0
{
}
Samples
List workflow runs across the org
GET
/v1/workflows/runs
List the runs the caller may read, newest first, across every workflow in the
caller's org: runs they started, plus runs of workflows they can read. Runs of
deleted workflows and draft test runs are excluded.
stats aggregates the WHOLE filtered set rather than the page returned, so a
summary rendered beside the table stays true while the table is paged.
sort=workflow orders by workflow name, case-insensitive with surrounding
whitespace ignored, across the entire result set; use workflow_id to isolate
one workflow's history. Every sort breaks ties newest run first, and
sort=duration puts unfinished runs last. run_number is the run's position
among its own workflow's runs, oldest is 1. search is a case-insensitive
substring match on the workflow name.
workflow_id, status and trigger_type may repeat to match any of several
values; different filters still narrow together.
date_to is inclusive to the end of the named day, so a bare YYYY-MM-DD does
not silently drop everything that ran after midnight on it.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
page
1-based page number.
Type
integer
Default
1Minimum
1page_size
Runs per page.
Type
integer
Default
20Maximum
100Minimum
1sort
Column to order by.
Type
string
Valid values
"created_at""duration""status""workflow"Default
"created_at"order
Sort direction.
Type
string
Valid values
"asc""desc"Default
"desc"workflow_id
Repeat to match several workflows.
status
Repeat to match any of several statuses.
trigger_type
Repeat to match any of several triggers.
search
Case-insensitive substring of the workflow name.
date_from
Start of the window, inclusive. Either an ISO-8601 instant (2026-09-15T00:00:00+08:00) or a bare YYYY-MM-DD, which means that whole calendar day in UTC. Send an instant with an offset to use another timezone.
date_to
End of the window, inclusive. A bare YYYY-MM-DD closes at the last instant of that day in UTC; an ISO-8601 instant is used exactly as given.
Responses
Successful Response
application/json
JSON "items": [ { "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "duration_ms": 0, "failed_count": 0, "id": "string", "input": { "additionalProperties": "string" }, "node_count": 0, "run_number": 0, "source_draft_id": "string", "source_draft_version_id": "string", "started_at": "string", "status": "string", "succeeded_count": 0, "total_cost": 0, "total_tokens": 0, "trigger_type": "string", "version_number": 0, "workflow_id": "string", "workflow_name": "string" } ], "page": 0, "page_size": 0, "stats": { "cancelled": 0, "failed": 0, "median_duration_ms": 0, "pending": 0, "rejected": 0, "running": 0, "succeeded": 0, "total": 0, "waiting": 0 }, "total": 0
{
}
Samples
Count workflow runs per time bucket
GET
/v1/workflows/runs/activity
Count the runs the caller may read per time bucket, split by status, over the
same filtered set as GET /workflows/runs. Both date_from and date_to are required.
Every bucket in the window is returned, empty ones as zeros, so the series can be
drawn without gap filling. Buckets are aligned to a fixed Monday origin, so
overlapping windows agree on the buckets they share and 1w bins are calendar
weeks.
Omit bucket to let the server pick the smallest of 5m, 15m, 1h, 1d,
1w that covers the window in about 31 buckets. A width too fine for the window
is widened (up to multiples of a week, reported as e.g. 2w) rather than
truncated; bucket and bucket_seconds report the width actually used.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
bucket
Bucket width; omit to fit the window.
workflow_id
Repeat to match several workflows.
status
Repeat to match any of several statuses.
trigger_type
Repeat to match any of several triggers.
search
Case-insensitive substring of the workflow name.
date_from
Start of the window, inclusive. Either an ISO-8601 instant (2026-09-15T00:00:00+08:00) or a bare YYYY-MM-DD, which means that whole calendar day in UTC. Send an instant with an offset to use another timezone.
date_to
End of the window, inclusive. A bare YYYY-MM-DD closes at the last instant of that day in UTC; an ISO-8601 instant is used exactly as given.
Responses
Successful Response
application/json
JSON "bucket": "string", "bucket_seconds": 0, "end": "string", "items": [ { "cancelled": 0, "failed": 0, "pending": 0, "rejected": 0, "running": 0, "start": "string", "succeeded": 0, "total": 0, "waiting": 0 } ], "start": "string"
{
}
Samples
Download a run file
GET
/v1/workflows/runs/files/{file_id}
Stream a file a run received or produced. Step outputs reference files by
file_id instead of carrying their bytes.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
file_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
JSON
[
]
Samples
List the size of every page of a PDF run file
GET
/v1/workflows/runs/files/{file_id}/pages
Page sizes for laying out the file's page images before they load.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
file_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "pages": [ { "height": 0, "width": 0 } ]
{
}
Samples
Get a page of a PDF run file as an image
GET
/v1/workflows/runs/files/{file_id}/pages/{page}
A PNG of one page. scale is pixels per PDF unit.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
file_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Query Parameters
scale
Pixels per PDF unit; large pages are capped.
Type
number
Default
2Maximum
3Minimum
1Responses
Successful Response
JSON
[
]
Samples
Get the words on a page of a PDF run file and where they are
GET
/v1/workflows/runs/files/{file_id}/pages/{page}/text
Words with boxes in page units, for selectable text over the page image.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
file_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Responses
Successful Response
application/json
JSON "height": 0, "width": 0, "words": [ { "text": "string", "x0": 0, "x1": 0, "y0": 0, "y1": 0 } ]
{
}
Samples
Get a run
GET
/v1/workflows/runs/{run_id}
Get a run with the detail of every step, for execution history and node-output
inspection. The response also carries events and actions.
A step's attempt reflects only its latest attempt; step_attempt_failed
events are the record of earlier ones. A rerun re-executes downstream nodes
under the same run id, so a node can carry more than one event per attempt
number, distinguished by created_at.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "actions": [ { "arguments": "string", "arguments_truncated": false, "call_id": "string", "created_at": "string", "error": "string", "id": "string", "node_id": "string", "output": "string", "output_truncated": false, "sequence": 0, "status": "string", "step_id": "string", "tool_name": "string" } ], "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "duration_ms": 0, "error": { "additionalProperties": "string" }, "events": [ { "actor_id": "string", "actor_name": "string", "created_at": "string", "id": "string", "kind": "string", "meta": { "additionalProperties": "string" }, "node_id": "string" } ], "id": "string", "input": { "additionalProperties": "string" }, "output": "string", "run_number": 0, "source_draft_id": "string", "source_draft_version_id": "string", "started_at": "string", "status": "string", "steps": [ { "agent_id": "string", "agent_name": "string", "attempt": 1, "completed_at": "string", "cost": 0, "drift_fsm_state": "string", "drift_score": 0, "duration_ms": 0, "error": { "additionalProperties": "string" }, "id": "string", "input_data": "string", "loop_index": 0, "matched_condition": "string", "model": "string", "node_id": "string", "node_type": "string", "output_data": "string", "routed_to": "string", "started_at": "string", "status": "string", "token_usage": { "additionalProperties": "string" } } ], "total_cost": 0, "total_tokens": 0, "trigger_type": "string", "version_id": "string", "version_number": 0, "workflow_id": "string", "workflow_name": "string"
{
}
Samples
Cancel a run
POST
/v1/workflows/runs/{run_id}/cancel
Cancel an in-flight run. Steps already running are signalled to stop; steps not
yet started are skipped.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "cancelled_at": "string", "id": "string", "status": "string"
{
}
Samples
Stream run events
GET
/v1/workflows/runs/{run_id}/events
Server-Sent Events stream of this run's step transitions and status changes,
pushed as they happen. Use it instead of polling GET /workflows/runs/{run_id}.
Each data: line is a JSON frame discriminated by type. The stream stays
open while the run is waiting and closes after a done frame once the run
reaches a terminal status (succeeded, failed, cancelled, rejected).
A quiet stream sends a : keepalive comment every 15 seconds; SSE clients
ignore comment lines.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON
[
]
Samples
Retry a failed run
POST
/v1/workflows/runs/{run_id}/retry
Create a new run from the same version and input as the original. The failed
run is never mutated. Valid only when the original run's status is failed.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Valid values
"resume""full"Default
"resume"Responses
Successful Response
application/json
JSON "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "id": "string", "input": { "additionalProperties": "string" }, "started_at": "string", "status": "string", "version_id": "string", "version_number": 0, "workflow_id": "string"
{
}
Samples
Resolve a waiting step
POST
/v1/workflows/runs/{run_id}/steps/{step_id}/decision
Resolve a checkpoint, file_upload or file_download step. When a run reaches
one it suspends: the step's status becomes waiting, its input_data holds the
upstream output to review, and the run's status becomes waiting. Submitting a
decision marks the step succeeded and resumes the run from where it paused.
For a checkpoint, output_data becomes a JSON string of decision, comment,
decided_by and upstream_input, so a downstream branch node can route on it.
Approving with edited_input replaces upstream_input with that text, so the
next node receives the reviewer's edit instead of the original.
For a file upload, output_data becomes the extracted file content; there is no
reject path — the user either uploads or cancels the run. Send exactly one of
file or document_id (a Data Room document you can read); otherwise 422.
Files are limited to 10 MB decoded; oversized returns 413.
For a file_download step, approving requires save_to: local, dataroom
(optional folder_id) or cloud (connection_id, optional folder_id). Its
output_data becomes file_id, filename and saved_to.
An agent step with variables, or whose agent can search the Data Room, waits
before it runs on every run. Its output_data lists what it needs under
inputs_required. Approving requires agent_inputs with a value for every listed
variables name, and a non-empty dataroom_scope this person can see when asked;
otherwise 422. The agent then runs with them. An agent step with
required_info also waits after it runs when it reports items it could not find
(inputs_required.required_info, with its reply); approving with a value for each
in agent_inputs.required_info adds them to the reply and continues to the next node.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Header Parameters
X-Webhook-Secret
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"step_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Any of
Default
""Pattern
"^(approved|rejected)$"Any of
Format
"uuid"Any of
Any of
Max Length
20971520Default
"application/octet-stream"Default
"utf-8"Pattern
"^(utf-8|base64)$"Any of
One of
Format
"uuid"Responses
Successful Response
application/json
JSON "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "id": "string", "input": { "additionalProperties": "string" }, "started_at": "string", "status": "string", "version_id": "string", "version_number": 0, "workflow_id": "string"
{
}
Samples
Re-run upstream nodes
POST
/v1/workflows/runs/{run_id}/steps/{step_id}/rerun
Re-run selected upstream nodes of a waiting checkpoint step, so an approver
can send work back for revision without restarting the run. Each listed node
must be an ancestor of the checkpoint. The checkpoint returns to waiting with
fresh upstream output.
Authenticate with a JWT, or with the workflow's X-Webhook-Secret header when
the run was started by a webhook trigger.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Header Parameters
X-Webhook-Secret
Path Parameters
run_id*
Type
Requiredstring
Format
"uuid"step_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Min Items
1Responses
Successful Response
application/json
JSON "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "id": "string", "input": { "additionalProperties": "string" }, "started_at": "string", "status": "string", "version_id": "string", "version_number": 0, "workflow_id": "string"
{
}
Samples
Delete a workflow
DELETE
/v1/workflows/{workflow_id}
Delete a workflow. Owner or organization admin only. The workflow stops
appearing in listings; its run history is retained.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Samples
Get a workflow
GET
/v1/workflows/{workflow_id}
Get full workflow details, including the definition of its active version.
Published workflows are immutable — there is no update endpoint. To change
metadata, the definition, or scope, edit the source draft and publish a new
version.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "active_version": { "created_at": "string", "created_by": "string", "created_by_name": "string", "definition": { "additionalProperties": "string" }, "has_webhook_token": false, "id": "string", "is_active": true, "node_count": 0, "validation_warnings": [ "string" ], "version_number": 0, "webhook_token": "string", "webhook_token_redacted": "string", "webhook_url": "string" }, "active_version_id": "string", "active_version_number": 0, "can_write": true, "created_at": "string", "created_by": "string", "created_by_name": "string", "delist_listing_id": "string", "description": "string", "has_webhook_token": false, "icon_name": "string", "id": "string", "last_run_at": "string", "listing_source_id": "string", "name": "string", "org_name": "string", "run_count": 0, "runs_url": "string", "source_draft_id": "string", "team_ids": [ "string" ], "updated_at": "string", "visibility": "string", "webhook_token_redacted": "string", "webhook_url": "string"
{
}
Samples
List a published workflow on the marketplace
POST
/v1/workflows/{workflow_id}/marketplace
Duplicates this published workflow and its active version into a new immutable listing readable by every organization on the platform. Webhook credentials are never copied: the listing has no webhook token and no principal claims. Re-listing the same workflow withdraws your previous listing.
The listing carries no agentSurface: a workflow is started by a trigger, so the question does not apply to it.
Returns 409 naming the agents this workflow uses that are not listed yet: list those first, then retry.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
What a publisher may still say about a listing, which is almost nothing.
A listing IS its build: the name, tags and icon are read off the published agent
or workflow rather than accepted here, so the catalog cannot disagree with the
library about what a thing is called. Only the blurb is an override, and only
because a sentence written for strangers is not always the internal one.
Overrides the build's own description. Omit to use that instead.
Any of
Max Length
220Min Length
1Responses
Successful Response
application/json
JSON "listingId": "string", "message": "Listed. Re-listing the same build withdraws the previous listing.", "resourceId": "string", "supersededListingId": "string"
{
}
Samples
Test a single node
POST
/v1/workflows/{workflow_id}/nodes/{node_id}/test
Execute one node of the active version in isolation against an input you
supply. Nothing is persisted — no run and no steps are created. Requires write
access.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"node_id*
Type
Requiredstring
Request Body
application/json
Responses
Successful Response
application/json
JSON "cost": 0, "duration_ms": 0, "output": "string", "token_usage": { "additionalProperties": "string" }
{
}
Samples
List runs
GET
/v1/workflows/{workflow_id}/runs
List the runs of a workflow, newest first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Query Parameters
page
Type
integer
Default
1Minimum
1page_size
Type
integer
Default
20Maximum
100Minimum
1status
sort
Type
string
Default
"created_at"Pattern
"^(created_at|duration)$"order
Type
string
Default
"desc"Pattern
"^(asc|desc)$"Responses
Successful Response
application/json
JSON "items": [ { "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "duration_ms": 0, "failed_count": 0, "id": "string", "input": { "additionalProperties": "string" }, "node_count": 0, "run_number": 0, "source_draft_id": "string", "source_draft_version_id": "string", "started_at": "string", "status": "string", "succeeded_count": 0, "total_cost": 0, "total_tokens": 0, "trigger_type": "string", "version_number": 0, "workflow_id": "string", "workflow_name": "string" } ], "page": 0, "page_size": 0, "total": 0
{
}
Samples
Trigger a run
POST
/v1/workflows/{workflow_id}/runs
Start a workflow run. Works for any workflow whose active or requested version
declares at least one trigger kind; an authenticated call always records
trigger_type: "api" and runs under the caller's claims, whatever kinds the
trigger node declares. Returns 409 when the workflow has no published version,
or when an agent step is bound to a chat agent: workflows run tool agents only,
so the run is refused with a message naming the step. Replace it with a tool
agent in the draft and publish again.
When the version's trigger node declares an input_schema, input is validated
against it and a mismatch returns 422 without creating the run. A missing
input is treated as {}, so a schema with required properties rejects an
empty call. Without an input_schema, any payload is accepted.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Any of
Any of
Format
"uuid"Responses
Successful Response
application/json
JSON "completed_at": "string", "created_at": "string", "created_by": "string", "created_by_name": "string", "id": "string", "input": { "additionalProperties": "string" }, "started_at": "string", "status": "string", "version_id": "string", "version_number": 0, "workflow_id": "string"
{
}
Samples
List versions
GET
/v1/workflows/{workflow_id}/versions
List every version of a workflow, newest first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "items": [ { "created_at": "string", "created_by": "string", "created_by_name": "string", "id": "string", "is_active": true, "node_count": 0, "version_number": 0 } ]
{
}
Samples
Rotate the webhook secret
POST
/v1/workflows/{workflow_id}/webhook-token/rotate
Issue a fresh webhook secret and return the plaintext once. The previous
secret stops working immediately, so any caller using it must be updated.
Requires write access. Returns 409 when the active version's trigger kinds do
not include webhook.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
workflow_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "created_at": "string", "webhook_token": "string", "webhook_url": "string"
{
}