Workflows API

The Workflows API lets external systems start a workflow by name with an input payload, schedule one for later, 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, and the commit emits a WorkflowRun.Created event to the workflow engine. The engine runs the definition’s entrypoint components that subscribe to that event, which is how a directly runnable workflow starts; an event-driven workflow starts from its own domain events instead. The response returns as soon as the run is created; 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. Record IDs under the well-known keys (vendor_id, service_id, assessment_id, engagement_id, contract_id, finding_id, vendor_document_id, questionnaire_response_id, intake_session_id, procurement_id, review_id, eval_id, portal_id, work_queue_item_id, radar_event_id, radar_case_id) tell the workflow’s actions which record to act on, and custom_fields passes custom field values to them. Any other key is stored as given. A number under a well-known key is converted to a string, and null values are dropped.

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.
422	Standard validation error	The request body failed schema validation. See API conventions.

Schedule a workflow run

POST

POST /v1/workflows/{workflow_name}/schedule

Schedules a run of a directly runnable workflow for a future time instead of starting it now. Returns 201 Created with the schedule. When the time comes, the run starts as if you had called Run a workflow with the same input.

Request body

integer

required

When to run, as a Unix timestamp in seconds. Must be in the future.

object

Workflow input, as for Run a workflow. Defaults to {}.

The endpoint honors Idempotency-Key. See Idempotency.

Example request

cURL

curl -X POST "https://api.coverbase.app/v1/workflows/quarterly-privacy-sweep/schedule" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_for": 1767225600, "input": { "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162" } }'

Response fields

The schedule carries id, workflow_definition_id (cbwd_...), scheduled_for, fired_at and canceled_at (both null until the schedule fires or is canceled), cancel_reason, payload (the input pinned at schedule time), and updated_at. The scheduling_* fields are null for schedules created through this endpoint.

Error responses

Status	Body	When
400	`{"detail": {"code": "workflow_not_direct_runnable", "message": "..."}}`	The workflow starts from domain events, not a direct run.
400	`{"detail": {"code": "scheduled_for_in_past", "message": "..."}}`	`scheduled_for` is not in the future.
404	`{"detail": {"code": "workflow_not_found", "message": "Workflow '...' not found."}}`	No workflow with that name exists for the org.
409	`{"detail": {"code": "workflow_archived", "message": "Workflow '...' is archived."}}`	The workflow is archived.
409	`{"detail": {"code": "workflow_disabled", "message": "Workflow '...' is disabled."}}`	The workflow is not enabled.

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 (for example, 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, for example, 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 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, for example, ?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 (for example, `limit` out of range, malformed `status`).

Getting started

API reference

Data import and export

Field reference

Integration workflows

AI, agents and MCP

Run a workflow

Path parameters

Request body

Headers

Example request

Example response

Response fields

Error responses

Schedule a workflow run

Request body

Example request

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

​Schedule a workflow run

​Request body

​Example request

​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

Schedule a workflow run

Request body

Example request

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