Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coverbase.com/llms.txt

Use this file to discover all available pages before exploring further.

The Workflows API lets external systems invoke a workflow by name and pass it parameters. Use this when the work you want to start doesn’t map cleanly to a single object event, for example a quarterly sweep of vendors matching a filter or an ad-hoc campaign. For workflows that are bound to object events (vendor.created, assessment.completed, etc.), prefer creating or updating the underlying object directly. See Triggering workflows from external systems for the three patterns.

​
Run a workflow

​
method
POST
POST /v1/workflows/{workflow_name}/run
Starts a new run of a named workflow with the provided input parameters. The workflow_name path parameter resolves to a CbWorkflowDefinition by its name field.

​
Path parameters

​
workflow_name
string
required
The unique name of the workflow as configured in the dashboard. This resolves to a CbWorkflowDefinition by name.
If your workflow names contain special characters that require URL-encoding, consider using POST /v1/workflows/runs with workflow_definition_id in the request body as an alternative.

​
Request body

​
input
object
required
Workflow-specific input parameters. Schema is defined per workflow during configuration. See the workflow’s detail page in the dashboard for its accepted input shape.

​
Headers

​
Authorization
string
required
Bearer <api-key>
​
Idempotency-Key
string
Optional. If the same key is sent twice within 24 hours, the second call returns the original response without starting a new run.

​
Example request

curl -X POST "https://api.coverbase.app/v1/workflows/quarterly-privacy-sweep/run" \
  -H "Authorization: Bearer <api-key>" \
  -H "Idempotency-Key: privacy-sweep-2026-q2" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "vendor_filter": { "tags": ["processes_pii"], "tier": ["1", "2"] },
      "due_date": "2026-06-30",
      "report_recipient": "privacy-team@example.com"
    }
  }'

​
Example response

{
  "workflow_run_id": "cbwfr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
  "workflow_definition_id": "cbwfdef_1a2b3c4d5e6f7a8b",
  "workflow_name": "quarterly-privacy-sweep",
  "status": "running",
  "started_at": 1746576000,
  "input": {
    "vendor_filter": { "tags": ["processes_pii"], "tier": ["1", "2"] },
    "due_date": "2026-06-30",
    "report_recipient": "privacy-team@example.com"
  }
}

​
Response fields

​
workflow_run_id
string
Unique identifier for this run. Use it to poll status or correlate downstream webhooks.
​
workflow_definition_id
string
The ID of the workflow definition that was run.
​
workflow_name
string
The name of the workflow that was invoked.
​
status
string
Initial status. Typically running. Other values include pending, paused, completed, failed, cancelled.
​
started_at
integer
Unix timestamp when the run started.
​
input
object
Echoes the input parameters sent in the request.

​
Get a workflow run

​
method
GET
GET /v1/workflows/runs/{workflow_run_id}
Returns the current state of a workflow run, including completed steps and any output.

​
Example request

cURL
curl -X GET "https://api.coverbase.app/v1/workflows/runs/cbwfr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b" \
  -H "Authorization: Bearer <api-key>"

​
Example response

{
  "workflow_run_id": "cbwfr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
  "workflow_definition_id": "cbwfdef_1a2b3c4d5e6f7a8b",
  "workflow_name": "quarterly-privacy-sweep",
  "status": "completed",
  "started_at": 1746576000,
  "completed_at": 1746579600,
  "checkpoints_reached": [
    "vendors_selected",
    "questionnaires_dispatched",
    "responses_aggregated",
    "report_delivered"
  ],
  "output": {
    "vendors_processed": 38,
    "responses_received": 32,
    "report_url": "https://dashboard.coverbase.app/reports/cbrpt_..."
  }
}

​
Response fields

​
workflow_definition_id
string
The definition ID that was run.
​
status
string
Current status of the run: pending, running, paused, completed, failed, or cancelled.
​
started_at
integer
Unix timestamp when the run started.
​
completed_at
integer or null
Unix timestamp when the run finished, if applicable.
​
checkpoints_reached
array
Array of checkpoint name strings reached during execution. Derived from the CbWorkflowRunStep records for this run.
​
output
object or null
Workflow output data, if the workflow produces output. Structure varies by workflow definition.

​
Subscribe to run progress

Polling is supported, but the recommended pattern is to subscribe to webhooks. The relevant events:
EventWhen it fires
workflow.checkpointA workflow reaches a configured checkpoint.
workflow.completedA workflow run finishes successfully.
workflow.failedA workflow run terminates with an error.
See the Webhooks reference for registration and payload format. Every event includes the workflow_run_id so you can correlate it back to the originating run.

​
Error responses

StatusCodeWhen
400invalid_inputThe input object does not match the workflow’s configured schema.
404workflow_not_foundNo workflow exists with the provided name for this org.
409idempotency_conflictA run already exists for this idempotency key. The original response is returned.
429rate_limitedPer-org workflow concurrency or rate limits exceeded. Inspect retry_after.