Workflows 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

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

string

required

The name of the workflow as configured for your org.

Request body

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

string

required

Bearer ak_...

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"
    }
  }'

import os
import requests

API_KEY = os.environ["COVERBASE_API_KEY"]
BASE_URL = "https://api.coverbase.app"

resp = requests.post(
    f"{BASE_URL}/v1/workflows/quarterly-privacy-sweep/run",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "privacy-sweep-2026-q2",
        "Content-Type": "application/json",
    },
    json={"input": {"vendor_filter": {"tags": ["processes_pii"]}, "due_date": "2026-06-30"}},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

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

string

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

string

The resolved workflow definition name.

string

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

integer

Unix timestamp (seconds) when the run was created.

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

GET

GET /v1/workflows/runs/{workflow_run_id}

Returns the current state of a workflow run.

Path parameters

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

string

The run ID (cbwr_...).

string | null

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

string | null

The workflow definition ID (cbwd_...).

string

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

integer

Unix timestamp (seconds) when the run was created.

integer | null

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

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

string

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

string | null

The workflow component this step ran.

string | null

The component’s display name.

string | null

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

string | null

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

string | null

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

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).

integer | null

Unix timestamp (seconds) when the step was recorded.

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

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

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.

string

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

integer

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

integer

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

integer

default:"100"

Page size. Min 1, max 500.

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

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.

integer

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

integer

Echoes the requested page size.

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`).

Getting started

Products

Control Set library

Trust & security

API Reference

Data Import & Export

Integration Workflows

AI, Agents, MCP

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

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