Overview

Do anything the console does from your own code: the Duraton HTTP API's base URL, authentication, conventions, and full endpoint map.

Everything the console does goes through Duraton's HTTP API, and so can you. It is plain JSON over HTTP - no SDK required to trigger events, read runs, or control them.

curl "$DURATON_URL/runs?limit=5" \
  -H "Authorization: Bearer $DURATON_API_KEY"

Base URL

Your workspace's base URL is shown in the console under API Keys (for example https://run.duraton.dev); it is the value you set DURATON_URL to. All paths below are relative to it. A workspace holds one or more projects that share this base URL; each project has its own API keys, and the key is what scopes a request to a single project.

Authentication

Every request needs an API key, presented as a Bearer token. Issue one in the console under API Keys:

curl "$DURATON_URL/runs" \
  -H "Authorization: Bearer $DURATON_API_KEY"

Keys carry a scope. A public (read-only) key can call the GET endpoints; writes (every POST, PATCH, and DELETE, plus the /connect upgrade) need a secret key.

Response	When
`401 Unauthorized`	The key is missing or unknown.
`403 Forbidden`	A public (read-only) key attempted a write, or the project is suspended.

Conventions

Request and response bodies are JSON. Send POST and PATCH bodies as a JSON object.
Reads return 200; writes return 200, 201, 202, or 204 depending on the route. The full map, and the failure codes, are in errors.
Listings are newest-first and bounded. GET /runs, GET /webhook-deliveries, and GET /webhook-source-deliveries use keyset pagination via the X-Next-Cursor header; the other listings take a limit (see limits).

Runs

Method + path	Purpose
`GET /runs`	List and filter runs, newest first, with an `X-Next-Cursor` header.
`GET /runs/{id}`	One run, with its input and result.
`GET /runs/{id}/steps`	The run's steps, in order.
`GET /runs/{id}/logs`	The run's `ctx.log` lines, oldest first.
`GET /runs/{id}/stream`	Live SSE timeline of one run (status + logs).
`GET /runs/stream`	Live SSE stream of run status transitions across the project.
`GET /runs/stats`	Aggregate run counts for a filter.
`GET /runs/timeseries`	Run counts bucketed over time, with duration averages.
`POST /runs/{id}/explain`	Stream a plain-language explanation of a failed run (SSE).
`GET /ai/spend`	AI token/cost rollup - totals plus by-hour, by-model, by-workflow.
`GET /sessions`	Conversation sessions: runs grouped by session id.

Control

Method + path	Purpose
`POST /runs/{id}/cancel`	Cancel a run.
`POST /runs/{id}/pause`	Pause a run at its next step boundary.
`POST /runs/{id}/resume`	Resume a paused run.
`POST /runs/{id}/replay`	Replay a finished run as a new run.
`POST /runs/{id}/retry-from-step`	Fork a finished run from a named step.
`POST /runs/{id}/fork`	Fork with one declared AI change as a shadow run.
`POST /runs/bulk-replay`	Replay every finished run matching a filter.
`GET /control-actions`	The control-action audit log, newest first.

Events

Method + path	Purpose
`POST /events`	Trigger workflows by sending an event. Returns `202`.
`GET /events`	Read the event log.
`GET /events/{id}`	One event log record.
`GET /events/stream`	Live event tail (Server-Sent Events).

Approvals and evals

Method + path	Purpose
`GET /approvals`	The project's approvals, newest first.
`GET /approvals/{id}`	One approval, with its proposed tool call.
`POST /approvals/{id}/decision`	Approve or deny an open approval; the parked run resumes.
`GET /runs/{id}/scores`	A run's scores, newest first.
`POST /runs/{id}/scores`	Record a score on a run. Returns `201`.
`GET /datasets` `POST /datasets`	List or create datasets of test cases.
`GET /datasets/{id}`	One dataset.
`GET /datasets/{id}/items` `POST /datasets/{id}/items`	List or append test cases.
`POST /datasets/{id}/eval`	Fan a dataset through a workflow as an eval run-set.
`GET /datasets/{id}/eval-runs`	The dataset's eval run-sets, newest first.
`GET /eval-sets/{id}`	One eval run-set with its score aggregates.

Webhooks

Method + path	Purpose
`POST /webhooks/{token}`	Public: a signature-verified inbound webhook mapped onto an event. Returns `202`.
`GET /webhook-deliveries`	The outbound delivery log, newest first.
`GET /webhook-deliveries/{id}`	One delivery with its attempt log.
`POST /webhook-deliveries/{id}/redeliver`	Re-queue a delivery for a fresh attempt. Returns `204`.
`GET /webhook-source-deliveries`	The inbound source delivery log, newest first.
`GET /webhook-source-deliveries/{id}`	One inbound delivery with its stored body and attempt log.
`POST /webhook-source-deliveries/{id}/replay`	Re-ingest a verified inbound delivery's stored body. Returns `200` with the replay outcome.
`GET` `POST` `PATCH` `DELETE /webhook-endpoints[/{id}]`	Manage outbound subscriptions (secrets shown once).
`GET /webhook-endpoints/stats`	Per-endpoint delivery health over a window.
`GET` `POST` `PATCH` `DELETE /webhook-sources[/{id}]`	Manage inbound sources (secrets shown once).

Registry

Method + path	Purpose
`GET /workflows`	List registered workflows, each with its `flowControl` config and the advisory `steps` manifest when declared.
`POST /workflows/{app}/{name}/trigger`	Start one off-schedule run of a registered workflow - works even for a cron-only workflow. Returns `202`.
`GET /apps`	List registered apps.
`GET /runners`	List connected runners with their metadata and liveness.
`GET /flow-state`	Live flow-control buffers (debounce, batch, concurrency draw).

The runner protocol (POST /register, the invoke call, GET /connect) is documented separately in the wire protocol, and the same operations are available to AI agents as MCP tools.

On this page