Workflow API Endpoints

Complete reference for workflow REST API endpoints, including workflow CRUD, workflow detail tabs, version history, analytics, related entities, and workflow-run helpers.

12 min read
apiworkflowsversions

The Workflows API mirrors the entire /workflows experience in the web app. You can list workflows, inspect full workflow detail data, update builder/configuration state, read workflow-specific runs, analytics, related entities, version history, and revert a workflow to a previous version.

UI Parity Coverage

  • Workflows list page: names, descriptions, CLI tool summary, timestamps, pagination, duplicate, delete, and bulk delete.
  • Workflow detail / Configuration: full workflow record, default sandbox config, pipeline steps, persona pipeline steps, workflow graph, timestamps.
  • Workflow detail / Builder: persistedworkflowGraph and execution pipelineStepspayloads.
  • Workflow detail / Runs: workflow-scoped runs with pagination.
  • Workflow detail / Analytics: KPIs, cost breakdown, success-rate series, runs-over-time, and related entities.
  • Workflow detail / Related: related personas, issues, and learning versions.
  • Workflow detail / Versions: version history and revert.
  • Run Workflow dialog: use POST /api/v1/runs/startto trigger a run from a workflow. If you want to attach reference images first, request an upload URL via POST /api/v1/files/upload-url.

Read Endpoints

GET /api/v1/workflows/list

Returns non-deleted workflows for the current project, including display metadata used by the table UI.

Query parameters:

  • limit (optional) - page size, default 50, max 100
  • cursor (optional) - cursor from the previous response

GET /api/v1/workflows/get

Returns the full workflow document used by the workflow details page, including config, pipeline steps, persona pipeline steps, and the saved workflow graph.

  • id (required) - workflow ID

GET /api/v1/workflows/runs

Returns the Runs tab for a workflow, including status, branch name, PR URL, run number/display ID, timestamps, and pagination metadata.

  • id (required) - workflow ID
  • limit (optional) - default 50, max 100
  • cursor (optional) - cursor from the previous response

GET /api/v1/workflows/analytics

Returns the Analytics tab payload for a workflow.

  • id (required) - workflow ID
  • days (optional) - lookback window, default 30
  • granularity (optional) - daily, weekly, or monthly

GET /api/v1/workflows/related

Returns the Related tab payload for a workflow: personas, issues, and learning versions linked to the workflow’s runs.

  • id (required) - workflow ID

GET /api/v1/workflows/versions

Returns the Versions tab payload for a workflow, including the current version number and snapshot metadata for each saved version.

  • id (required) - workflow ID

Write Endpoints

POST /api/v1/workflows/create

Create a workflow blueprint.

Supported write fields include:

  • name (required)
  • description
  • type
  • defaultConfig
  • maxIterations
  • pipelineSteps
  • personaPipelineSteps
  • workflowGraph

At least one of pipelineSteps or personaPipelineSteps must be provided.

POST /api/v1/workflows/update

Update any subset of workflow fields. API updates also snapshot the previous workflow state into version history so the Versions tab stays in sync with changes made outside the UI.

{
  "workflowId": "...",
  "name": "Release hardening",
  "defaultConfig": {
    "templateId": "claude",
    "timeoutMs": 3600000,
    "memoryMb": 4096,
    "cpuCount": 4
  },
  "pipelineSteps": [
    { "type": "designer", "cliId": "claude", "model": "claude-opus-4-7" },
    { "type": "checker", "cliId": "claude", "model": "claude-sonnet-4-6" }
  ],
  "workflowGraph": { "nodes": [], "edges": [] }
}

POST /api/v1/workflows/versions/revert

Revert a workflow to a previous version. The API snapshots the current state first, just like the web UI.

{ "workflowId": "...", "versionId": "..." }

POST /api/v1/workflows/duplicate

Duplicate a workflow, including persona pipeline steps, execution steps, and the saved builder graph.

POST /api/v1/workflows/delete

Soft-delete a workflow.

POST /api/v1/workflows/restore

Restore a soft-deleted workflow.

POST /api/v1/workflows/permanent-delete

Permanently delete a workflow.

POST /api/v1/workflows/rename

Rename a workflow.

POST /api/v1/workflows/bulk-delete

Bulk soft-delete workflows.

Running a Workflow from the API

The Run button on the workflow list/detail pages maps to POST /api/v1/runs/start. Typical request fields include:

  • workflowId (required)
  • prompt (required)
  • githubRepoUrl (optional)
  • branchName (optional)
  • config (optional sandbox config override)
  • referenceImageIds (optional uploaded images)

To attach images like the UI does, first request an upload URL with POST /api/v1/files/upload-url, upload the binary to the returned URL, then pass the resulting storageId values as referenceImageIds when starting the run.

Workflow Data Model

Workflow responses can include:

  • name, description, type
  • defaultConfig including tool/model/resource fields
  • pipelineSteps and personaPipelineSteps
  • workflowGraph for the Builder tab
  • defaultCheckerInstructions and defaultOptimizerInstructions
  • createdAt, updatedAt, deletedAt
  • display fields such as CLI tool labels used by the list UI