> ## Documentation Index
> Fetch the complete documentation index at: https://docs.persistence.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API

> Start, inspect, cancel, and wake published event-to-call workflow runs.

Use the Workflows API after you publish an event-to-call [workflow](/deploy/workflows) in the dashboard. These routes start and control runs. They do not create or edit the graph.

Every request requires a workspace API key in the `X-API-Key` header. Use the `workflow run` scope to start, cancel, or wake a run. Add `workflow read` to check status.

The API key determines the workspace, so these paths do not include a workspace ID.

<CardGroup cols={1}>
  <Card title="Start a run" icon="play" href="/api-reference/workflows/start-run">
    `POST /v1/workflows/{workflowId}/run` — queue a published workflow with `context`.
  </Card>

  <Card title="Get run status" icon="list-checks" href="/api-reference/workflows/get-run">
    `GET /v1/workflows/{workflowId}/runs/{runId}` — inspect status, context, and output.
  </Card>

  <Card title="Cancel a run" icon="circle-stop" href="/api-reference/workflows/cancel-run">
    `POST /v1/workflows/{workflowId}/runs/{runId}/cancel` — stop one active run.
  </Card>

  <Card title="Cancel runs" icon="ban" href="/api-reference/workflows/cancel-runs">
    `POST /v1/workflows/{workflowId}/runs/cancel` — stop runs by concurrency key, or all of them.
  </Card>

  <Card title="Wake waiting runs" icon="alarm-clock" href="/api-reference/workflows/wake-runs">
    `POST /v1/workflows/{workflowId}/runs/wake` — continue runs sleeping at a wait step.
  </Card>
</CardGroup>

Publish the workflow first. Drafts reject start requests.

Reuse `Idempotency-Key` when you retry the same start. Add `Concurrency-Key` when only one active run should exist for a store, ticket, or similar key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.