Workflows API - Coverbase API

The Workflows API lets external systems start a workflow by name with an arbitrary input payload, and read the state of a run. All endpoints are org-scoped to the API key. See API conventions for authentication, IDs, timestamps, idempotency, and the error envelope.

Run a workflow

method

POST

POST /v1/workflows/{workflow_name}/run

Starts a new run of the named workflow. Returns 201 Created. The workflow_name path segment is matched against the workflow definition’s name for your org. The run row is created and committed, then a Workflow.RunRequested event is dispatched to the workflow engine, which executes the definition’s entrypoint components. The response returns as soon as the run is created and the event is enqueued — poll Get a workflow run for progress.

Path parameters

workflow_name

string

required

The name of the workflow as configured for your org.

Request body

input

object

Workflow input parameters. Optional — defaults to {}. The value is stored and echoed back on the response; its schema is workflow-specific and is not validated by this endpoint.

Headers

Authorization

string

required

Bearer ak_...

Idempotency-Key

string

Optional. If the same key is sent again within 24 hours for this endpoint, the original response is returned and no new run is started. See Idempotency.

Example request

curl -X POST "https://api.coverbase.app/v1/workflows/quarterly-privacy-sweep/run" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Idempotency-Key: privacy-sweep-2026-q2" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "vendor_filter": { "tags": ["processes_pii"] },
      "due_date": "2026-06-30"
    }
  }'

Example response

201 Created:

{
  "workflow_run_id": "cbwr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
  "workflow_name": "quarterly-privacy-sweep",
  "status": "started",
  "started_at": 1746576000,
  "input": {
    "vendor_filter": { "tags": ["processes_pii"] },
    "due_date": "2026-06-30"
  }
}

Response fields

workflow_run_id

string

Identifier for this run (cbwr_...). Use it with the get-run endpoint.

workflow_name

string

The resolved workflow definition name.

status

string

Run status. One of: started, completed, canceled, failed. A new run is started.

started_at

integer

Unix timestamp (seconds) when the run was created.

input

object

Echoes the input sent in the request.

Error responses

Status	Body	When
404	`{"detail": {"code": "workflow_not_found", "message": "Workflow '...' not found."}}`	No workflow with that name exists for the org.
409	`{"detail": {"code": "workflow_disabled", "message": "Workflow '...' is disabled."}}`	The workflow exists but is not enabled.
502	`{"detail": {"code": "workflow_dispatch_failed", "message": "Workflow run was created but could not be dispatched. Retry with the same workflow run id (...)."}}`	The run row was created but the dispatch event failed. The run ID is in the message; safe to retry.
422	Standard validation error	The request body failed schema validation. See API conventions.

Get a workflow run

method

GET

GET /v1/workflows/runs/{workflow_run_id}

Returns the current state of a workflow run.

Path parameters

workflow_run_id

string

required

The run ID (cbwr_...).

Example request

cURL

curl -X GET "https://api.coverbase.app/v1/workflows/runs/cbwr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "workflow_run_id": "cbwr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
  "workflow_name": "quarterly-privacy-sweep",
  "workflow_definition_id": "cbwd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "status": "completed",
  "started_at": 1746576000,
  "completed_at": 1746579600,
  "steps": [
    {
      "step_id": "cbwrs_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "component_id": "cbwc_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
      "component_name": "Send questionnaire",
      "action_type": "send_questionnaire",
      "status": "success",
      "message": null,
      "artifacts": [
        { "artifact_type": "vendor", "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162", "role": "trigger" },
        { "artifact_type": "questionnaire_response", "id": "cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a", "role": "result" }
      ],
      "created_at": 1746576540,
      "updated_at": 1746576600
    }
  ]
}

Response fields

workflow_run_id

string

The run ID (cbwr_...).

workflow_name

string | null

The workflow definition name, or null if the definition could not be resolved.

workflow_definition_id

string | null

The workflow definition ID (cbwd_...).

status

string

Run status. One of: started, completed, canceled, failed.

started_at

integer

Unix timestamp (seconds) when the run was created.

completed_at

integer | null

Unix timestamp (seconds) when the run finished. Populated only when status is completed, failed, or canceled; otherwise null.

steps

object[]

Executed steps for this run (empty array if none yet). Each step records both the component that ran and the outcome of that component’s action. Each step has:

Show step fields

step_id

string

The run-step ID (cbwrs_...).

component_id

string | null

The workflow component this step ran.

component_name

string | null

The component’s display name.

action_type

string | null

The component’s action type (e.g. send_questionnaire), when available.

status

string | null

Action outcome. One of success, failed, skipped, or null if the engine has not yet recorded a result for this step.

message

string | null

Optional human-readable explanation. Set on failure to surface the error; set on skipped to explain why; usually null on success.

artifacts

object[]

Entities the step consumed or produced. Each entry has artifact_type (the canonical target type, e.g. vendor, assessment, questionnaire_response), id (the entity ID), and role (trigger for entities that fed into the step; result for entities the step created or modified).

created_at

integer | null

Unix timestamp (seconds) when the step was recorded.

updated_at

integer | null

Unix timestamp (seconds) of the step’s last update.

Poll this endpoint until status is terminal (completed, canceled, or failed); steps[] grows as the engine progresses, and each step’s status and artifacts reflect what that stage actually did.

Error responses

Status	Body	When
404	`{"detail": {"code": "workflow_run_not_found", "message": "Workflow run not found."}}`	The `workflow_run_id` does not exist or is not in the API key’s org.

List workflow runs

method

GET

GET /v1/workflows/runs

Returns workflow runs for the org, newest first. Use this when you don’t already know the run ID — for example, to discover runs created by other systems or by Coverbase’s internal automations, or to reconcile run history against an external scheduler.

Query parameters

workflow_name

string

Filter to runs of a specific workflow definition by name. Returns 404 workflow_not_found if no workflow with that name exists for the org.

status

string

Filter by run status. Repeat to include multiple statuses, e.g. ?status=started&status=failed. Valid values: started, completed, canceled, failed.

created_at_after

integer

Unix timestamp (seconds). Include only runs created at or after this time.

created_at_before

integer

Unix timestamp (seconds). Include only runs created at or before this time.

limit

integer

default:"100"

Page size. Min 1, max 500.

offset

integer

default:"0"

Pagination offset.

Example request

cURL

curl -X GET "https://api.coverbase.app/v1/workflows/runs?workflow_name=quarterly-privacy-sweep&status=failed&limit=20" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "data": [
    {
      "workflow_run_id": "cbwr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
      "workflow_name": "quarterly-privacy-sweep",
      "workflow_definition_id": "cbwd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "status": "failed",
      "started_at": 1746576000,
      "completed_at": 1746576720,
      "step_count": 3
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Response fields

data

object[]

Paginated list of run summaries. Each entry mirrors the keys of Get a workflow run, minus steps[] and plus step_count. Fetch the full run via GET /v1/workflows/runs/{workflow_run_id} when you need per-stage outcomes.

total

integer

Total number of runs matching the filters (across all pages).

limit

integer

Echoes the requested page size.

offset

integer

Echoes the requested offset.

Error responses

Status	Body	When
404	`{"detail": {"code": "workflow_not_found", "message": "Workflow '...' not found."}}`	`workflow_name` was supplied but no workflow with that name exists for the org.
422	Standard validation error	A query parameter failed validation (e.g. `limit` out of range, malformed `status`).

​Run a workflow

​Path parameters

​Request body

​Headers

​Example request

​Example response

​Response fields

​Error responses

​Get a workflow run

​Path parameters

​Example request

​Example response

​Response fields

​Error responses

​List workflow runs

​Query parameters

​Example request

​Example response

​Response fields

​Error responses

Run a workflow

Path parameters

Request body

Headers

Example request

Example response

Response fields

Error responses

Get a workflow run

Path parameters

Example request

Example response

Response fields

Error responses

List workflow runs

Query parameters

Example request

Example response

Response fields

Error responses