Workflow Runs

A workflow run is a single execution of a workflow definition. Each run tracks its own state, step progress, and output independently.

Create a Workflow Run

POST /v1/workflow-runs

Starts a new execution of a workflow definition. If you provide an idempotencyKey that matches an existing run, the existing run is returned instead of creating a duplicate.

Request Body

Field	Type	Required	Description
`definitionId`	`string`	Yes	ID of the workflow definition to execute
`input`	`object`	No	Key-value input data passed to the workflow (defaults to `{}`)
`idempotencyKey`	`string`	No	Unique key to prevent duplicate runs (max 255 characters)

Example Request

curl -X POST https://api.stevora.dev/v1/workflow-runs \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionId": "wfdef_abc123",
    "input": {
      "companyName": "Acme Corp",
      "contactEmail": "jane@acme.com"
    },
    "idempotencyKey": "onboard-acme-2026-04-02"
  }'

Response `201 Created`

Returned when a new run is created:

{
  "success": true,
  "data": {
    "id": "wfrun_def456",
    "workspaceId": "ws_xyz789",
    "definitionId": "wfdef_abc123",
    "status": "PENDING",
    "input": {
      "companyName": "Acme Corp",
      "contactEmail": "jane@acme.com"
    },
    "output": null,
    "idempotencyKey": "onboard-acme-2026-04-02",
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  }
}

Response `200 OK`

Returned when the idempotencyKey matches an existing run (no new run created):

{
  "success": true,
  "data": {
    "id": "wfrun_existing",
    "status": "RUNNING",
    ...
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Missing `definitionId` or invalid fields
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Referenced workflow definition not found

List Workflow Runs

GET /v1/workflow-runs

Returns a paginated list of workflow runs in your workspace.

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number (min 1)
`pageSize`	`integer`	`20`	Results per page (1-100)
`status`	`string`	--	Filter by status: `PENDING`, `RUNNING`, `WAITING`, `PAUSED`, `COMPLETED`, `FAILED`, `CANCELLED`
`definitionId`	`string`	--	Filter by workflow definition ID

Example Request

curl "https://api.stevora.dev/v1/workflow-runs?status=RUNNING&pageSize=10" \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "wfrun_def456",
      "workspaceId": "ws_xyz789",
      "definitionId": "wfdef_abc123",
      "status": "RUNNING",
      "input": { "companyName": "Acme Corp" },
      "output": null,
      "createdAt": "2026-04-02T12:00:00.000Z",
      "updatedAt": "2026-04-02T12:01:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid query parameters
401	`AUTH_ERROR`	Missing or invalid API key

Get a Workflow Run

GET /v1/workflow-runs/:id

Returns the current state of a single workflow run.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Example Request

curl https://api.stevora.dev/v1/workflow-runs/wfrun_def456 \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "wfrun_def456",
    "workspaceId": "ws_xyz789",
    "definitionId": "wfdef_abc123",
    "status": "RUNNING",
    "input": { "companyName": "Acme Corp" },
    "output": null,
    "currentStepIndex": 1,
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:01:00.000Z"
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Run does not exist or belongs to another workspace

Cancel a Workflow Run

POST /v1/workflow-runs/:id/cancel

Cancels a running or waiting workflow. Completed, failed, and already-cancelled runs cannot be cancelled.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Example Request

curl -X POST https://api.stevora.dev/v1/workflow-runs/wfrun_def456/cancel \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "wfrun_def456",
    "status": "CANCELLED",
    "updatedAt": "2026-04-02T12:05:00.000Z"
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Run not found
409	`CONFLICT`	Run is not in a cancellable state

Resume a Workflow Run

POST /v1/workflow-runs/:id/resume

Resumes a workflow that is waiting for an external signal. Use this to deliver signals to runs paused at external_event or wait steps.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Request Body

Field	Type	Required	Description
`signalType`	`string`	Yes	The signal type the step is waiting for
`payload`	`object`	No	Data to deliver with the signal (defaults to `{}`)

Example Request

curl -X POST https://api.stevora.dev/v1/workflow-runs/wfrun_def456/resume \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "signalType": "payment.confirmed",
    "payload": {
      "transactionId": "txn_98765",
      "amount": 499.00
    }
  }'

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "wfrun_def456",
    "status": "RUNNING",
    "updatedAt": "2026-04-02T12:10:00.000Z"
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Missing `signalType` or invalid fields
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Run not found
409	`CONFLICT`	Run is not in a waiting state

Retry a Workflow Run

POST /v1/workflow-runs/:id/retry

Retries a failed workflow run from the step that failed. The run must be in FAILED status.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Example Request

curl -X POST https://api.stevora.dev/v1/workflow-runs/wfrun_def456/retry \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "wfrun_def456",
    "status": "RUNNING",
    "updatedAt": "2026-04-02T12:15:00.000Z"
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Run not found
409	`CONFLICT`	Run is not in `FAILED` status

Run Statuses

Status	Description
`PENDING`	Run has been created but execution has not started
`RUNNING`	Run is actively executing steps
`WAITING`	Run is paused at an `external_event` or `wait` step
`PAUSED`	Run is paused at an `approval` step
`COMPLETED`	All steps finished successfully
`FAILED`	A step failed after exhausting retries
`CANCELLED`	Run was cancelled via the API

Workflow Runs

On this page