> ## Documentation Index > Fetch the complete documentation index at: https://docs.duraton.dev/llms.txt > Use this file to discover all available pages before exploring further. # REST reference > Every /workflows/v1 route, its keys, lists, idempotency, the live stream and every error code. Durable workflows for a project: send events, start and inspect runs, follow them live, schedule them and wait on outside input. Your code runs in your own worker, which connects to the project and runs each step. Base URL: `https://./workflows/v1`. ## Keys | Key | What it may do | | - | - | | Secret (`dtn_sk_`) | Everything on this page, and connect a worker | | Worker (`dtn_wk_`) | Connect a worker only | | Publishable (`dtn_pk_`) | Nothing here: `403 api_key_kind_not_allowed` | Send the key in the `apikey` header. Never put a key in a URL. ## Routes | Route | Answer | | - | - | | `POST /events` | `202` with one result for an object body, `202 { data: [...] }` for an array | | `GET /events` | `{ data, nextCursor }` of the events the project received, newest first; filters `name`, `app`, `source` (`api`, `emit` or `webhook`), `since` (included), `until` (excluded) | | `GET /events/{id}` | One received event; `404 not_found` for an id the project never received | | `GET /workflows` | `{ data, nextCursor }` of the workflows your workers registered | | `GET /workflows/{app}/{name}` | One workflow | | `POST /workflows/{app}/{name}/runs` | `201` with the new run; body `{ input?, startAfter?, ttlSeconds?, tags?, dedupeId? }`; `429 quota_exceeded` while the project holds `workflows.max_queued_runs` queued runs, with no `Retry-After`: retry once some have started | | `GET /runs` | `{ data, nextCursor }`, newest first; filters `app`, `workflow`, `status`, `runType`, `eventId`, `since`, `until`, `buildId`, `tag.=` (repeatable) | | `GET /runs/{id}` | One run | | `GET /runs/{id}/steps` | `{ data, nextCursor }` of its steps, each with its `kind` | | `GET /runs/{id}/logs` | `{ data, nextCursor }` of the lines its worker logged, newest first | | `GET /runs/{id}/stream` | The run's live timeline, Server-Sent Events | | `GET /runs/stream` | Every run's status changes, Server-Sent Events (below) | | `POST /runs/{id}/cancel` | The cancelled run; body `{ reason? }` | | `POST /runs/{id}/pause` | The paused run, with `pausedBy`; no body | | `POST /runs/{id}/resume` | The run, `queued` again; no body | | `POST /runs/{id}/replay` | `201` with the new run; body `{ fromStep?, input? }` | | `POST /runs/bulk_cancel` | `{ matched, cancelled, skipped, failed, capped }`, at most 500 runs a call; body `app`, `workflow`, `status`, `runType`, `since`, `tags` | | `POST /runs/bulk_replay` | `{ matched, replayed, skipped, failed, capped }`; body `app`, `workflow`, `status`, `runType`, `since` and `fromStep?`, never `input` (`422`); a run without that step counts in `failed` | | `GET, POST /schedules`; `GET, PATCH, DELETE /schedules/{id}`; `POST /schedules/{id}/pause`, `/resume` | Schedules; a create while the project holds `workflows.max_schedules` is `429 quota_exceeded`, with no `Retry-After` | | `POST /cron_previews` | `{ data: [...] }`, the next fire times for `{ cron, timezone?, count? }` (at most 10) | | `POST /tokens`; `GET /tokens`, `/tokens/{id}`; `POST /tokens/{id}/complete` | Wait tokens | | `GET /runners` | The workers connected now, a list | | `GET /limits` | `{ limits, counts }`, the project's workflow limits and what they measure now | | `GET /usage` | `{ from, to, totals }`, the project's workflows and webhooks usage over `from` (included) to `to` (excluded), both required | | `GET, POST /webhook_endpoints`; `GET, PATCH, DELETE /webhook_endpoints/{id}` | Webhook endpoints (see Webhooks); an endpoint slowed after its receiver answered `429`, `502` or `504` carries `throttleDelayMs` (above 0) and `throttledUntil` | | `GET /connect` | A worker's WebSocket, subprotocol `duraton.connect.v0` | Lists take `limit` (1 to 100, default 20) and an opaque `cursor`; only `nextCursor: null` ends a list. There is no total. Every change takes an optional `Idempotency-Key` header: the same key and body answers the first result again; another body under the same key is `422 idempotency_key_reused`. A body field this page does not name is ignored, not refused: it has no effect, so never rely on one. The exceptions are on the bulk calls, so one never reaches runs you did not name: `input` on `POST /runs/bulk_replay` is `422`, and a `GET /runs` filter a bulk call cannot select by (`eventId`, `until` and `buildId` on both, `tags` on a replay) is `422 workflow_bulk_filter_unsupported`, its `fields` naming them. ## Pause and resume a run `POST /runs/{id}/pause` holds a `queued`, `running` or `waiting` run where it is: it keeps every finished step, and nothing more of it runs until it is resumed. A step already running finishes first. The run answers `status: "paused"` and `pausedBy: { reason: "manual", since }`. Pausing a paused run answers it again with a new `since`. `POST /runs/{id}/resume` queues it again and clears `pausedBy`; it carries on from the step it stopped at. A run waiting on an event stays `queued` until the event arrives. | Refusal | When | | - | - | | `409 workflow_run_finished` | Pausing a run that has finished | | `409 conflict` | Pausing a run that is waiting for a decision (`needs_attention`) | | `409 workflow_run_not_paused` | Resuming a run that is not paused | | `409 workflows_suspended` | Resuming while the project's workflows are off; pausing still works | | `404 workflow_run_not_found` | A run the project does not have | ## Run logs `GET /runs/{id}/logs` lists what the run's worker logged with the handler's `log`, newest first. Each line is `{ seq, ts, level, message, fields?, scope, attempt }`: `scope` is the step that logged it, or `@root` outside a step, and `attempt` is that step's attempt. ## Steps Each step carries `kind`, what it does: `run`, `sleep`, `wait`, `invoke`, `emit`, `webhook` or `approval`. A step recorded before kinds existed has none. ## Following runs live `GET /runs/stream?kinds=run_status,step_status&since=