Workflows API
Create, configure, and run multi-step AI workflows on your entities.
4 min read
Workflows API
Create, configure, and run multi-step AI workflows on your entities. Workflows chain together steps like AI generation, validation, publishing, and notification into repeatable pipelines.
List Workflows
GET /api/v1/workflows
Response
idstring
Unique identifier for the workflow.
namestring
Display name of the workflow.
descriptionstring
Optional description of what the workflow does.
statusstring
Current status: `"active"`, `"draft"`, or `"archived"`.
stepsCountnumber
Total number of steps configured in the workflow.
lastRunAtnumber
Timestamp (ms) of the most recent execution, or `null` if never run.
Get Workflow
GET /api/v1/workflows/:id
Returns the workflow including its full step configuration.
Response
idstring
Unique identifier for the workflow.
namestring
Display name of the workflow.
descriptionstring
Optional description of what the workflow does.
statusstring
Current status: `"active"`, `"draft"`, or `"archived"`.
stepsCountnumber
Total number of steps in the workflow.
lastRunAtnumber
Timestamp (ms) of the most recent execution.
stepsobject[]
Ordered array of step configurations.
steps[].idstring
Unique identifier for the step.
steps[].typestring
Step type: `"ai_generate"`, `"validate"`, `"publish"`, `"notify"`, `"transform"`, or `"condition"`.
steps[].configobject
Type-specific configuration for the step.
Create Workflow
POST /api/v1/workflows
Request Body
namestringrequired
Display name for the workflow.
descriptionstring
Optional description of what the workflow does.
entityTypeIdstringrequired
The entity type this workflow operates on.
stepsobject[]required
Ordered array of step configurations. Each step must include a `type` and `config` object.
Note
Step types are: `"ai_generate"`, `"validate"`, `"publish"`, `"notify"`, `"transform"`, and `"condition"`. Each type has its own config schema — see the step type reference in the dashboard for available options.
Run Workflow
POST /api/v1/workflows/:id/run
Executes the workflow on a set of entities. Returns a job ID for tracking progress.
Request Body
entityIdsstring[]required
Array of entity IDs to run the workflow on.
Response
jobIdstring
The ID of the background job created for this run. Use the Jobs API to track progress.
Tip
Use the [Jobs API](/docs/api-jobs) to monitor run progress, view logs, and cancel if needed.
Get Run Status
GET /api/v1/workflows/:id/runs/:runId
Response
idstring
Unique identifier for the run.
statusstring
Run status: `"pending"`, `"running"`, `"completed"`, `"failed"`, or `"cancelled"`.
progressobject
Progress breakdown for the run.
progress.totalnumber
Total number of entities in the run.
progress.completednumber
Number of entities that completed all steps successfully.
progress.failednumber
Number of entities that failed during execution.
startedAtnumber
Timestamp (ms) when the run started.
completedAtnumber
Timestamp (ms) when the run finished, or `null` if still running.
Was this helpful?