API overview
Base URL, authentication with API keys and scopes, versioning, request and response format, and your first request to the Duun API.
On this page
The Duun API lets you start and steer runs, manage factories and workflows, and read usage from your own code. It is a JSON-over-HTTPS REST API: predictable resource URLs, standard HTTP verbs and status codes, and bearer-token authentication.
Everything the API does, you can also do in the app. The API is the right tool when you want to start runs from CI, sync workflows from a repository, build a status page from run events, or pull usage into your own reporting.
Base URL
Every endpoint lives under one base URL:
https://api.duun.ai/v1All requests must use HTTPS. Plain HTTP requests are refused, not redirected.
Authentication
The API authenticates with workspace API keys sent as a bearer token:
GET /v1/runs HTTP/1.1
Host: api.duun.ai
Authorization: Bearer duun_sk_4f9a…A key acts as the workspace, not as a person. Runs it starts show API as their source, and anything it changes is recorded in the audit log with the key’s name.
Create an API key
- Open Settings → API keys & secrets and go to Duun API keys.
- Select New API key, give it a name that says where it runs (for example
ci-github-actions), and pick its scopes. - Copy the key. It starts with
duun_sk_and is shown once; store it in your secret manager.
Only Admins can create, rotate or revoke API keys. Revoking a key takes effect immediately: requests with it return 401 authentication_error.
Scopes
Give each key the smallest set of scopes it needs. A request outside the key’s scopes returns 403 permission_denied with code missing_scope.
| Scope | Allows |
|---|---|
runs:read | List and read runs, their asks and their logs |
runs:write | Start, cancel, pause, resume and restart runs; resolve asks |
factories:read | List and read factories |
factories:write | Create, update, pause, resume and archive factories |
workflows:read | Read workflows and their versions |
workflows:write | Create workflows, apply versions, restore, test, pause and resume |
agents:read | List and read agents |
agents:write | Create, update and delete custom agents |
skills:read | List and read workspace skills |
skills:write | Create, update, delete and publish skills |
commands:read | List and read slash commands |
commands:write | Create, update and delete slash commands |
webhooks:read | List webhook endpoints, deliveries and trigger URLs |
webhooks:write | Create, update, rotate and delete webhook endpoints and trigger URLs |
usage:read | Read usage reports, credit balance and budgets |
Write scopes don’t imply read scopes. A CI job that starts runs and waits for them to finish needs both runs:write and runs:read.
Versioning
The major version is in the path (/v1). Within a major version we add fields, endpoints and enum values without notice, so write clients that ignore fields they don’t recognise and handle unknown enum values gracefully.
Changes that could break a client ship as a dated revision. To pin one, send the Duun-Version header:
Duun-Version: 2026-11-01Without the header, requests use the latest revision. Every response echoes the revision it was served with in its own Duun-Version header, so you can log it alongside failures. Webhook events carry the same value in api_version.
Requests and responses
- Send request bodies as JSON with
Content-Type: application/json. The one exception is uploading a skill bundle, which usesmultipart/form-data. - Field names are
snake_case. - Timestamps are ISO 8601 strings in UTC, for example
2026-11-15T09:42:07Z. - Money is a decimal number of US dollars in fields ending in
_usd, for example"spent_usd": 1.84. - Every object has an
idwith a type prefix and anobjectfield naming its type. - Fields with no value are
null, not omitted.
| Prefix | Object |
|---|---|
run_ | Run |
ask_ | Ask (something waiting on a person) |
fac_ | Factory |
wf_ | Workflow |
agt_ | Agent |
skl_ | Skill |
cmd_ | Slash command |
whe_ | Webhook endpoint |
whd_ | Webhook delivery |
evt_ | Event |
trg_ | Trigger URL |
prj_ | Project |
ws_ | Workspace |
Successful requests return 200 OK, or 201 Created when they create something. Asynchronous actions such as cancelling a run return 200 with the resource in its new state (for example status: "running" while the agent finishes its current tool call). Errors return a 4xx or 5xx status with an error object; see Pagination, errors and limits.
Request IDs
Every response carries a Duun-Request-Id header:
Duun-Request-Id: req_8Kc2Vd91TfQxError bodies repeat it as error.request_id. Log it with every failed call and include it when you contact support; it lets us find the exact request.
Your first request
This lists the five most recent runs that are waiting on a person. It needs a key with runs:read.
curl "https://api.duun.ai/v1/runs?status=waiting&limit=5" \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
const page = await duun.runs.list({ status: "waiting", limit: 5 });
for (const run of page.data) {
console.log(run.id, run.title, run.ask?.title);
}from duun import Duun
client = Duun() # reads DUUN_API_KEY
page = client.runs.list(status="waiting", limit=5)
for run in page.data:
print(run.id, run.title, run.ask and run.ask.title){
"object": "list",
"data": [
{
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "waiting",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": "plan",
"branch": "duun/plt-482-idempotency-keys",
"ask": { "id": "ask_3h2Lm8", "kind": "approve_plan", "title": "Approve the plan", "created_at": "2026-11-15T09:42:07Z" },
"pull_request": null,
"cost": { "spent_usd": 1.84, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"created_at": "2026-11-15T09:38:12Z",
"updated_at": "2026-11-15T09:42:07Z",
"finished_at": null
}
],
"has_more": false,
"next_cursor": null
}SDKs and CLI
You don’t have to call the HTTP API by hand:
- The TypeScript SDK (
@duun/sdk) and Python SDK (duun) wrap every endpoint, paginate for you, retry rate-limited and transient failures with the same idempotency key, and verify webhook signatures. - The
duunCLI covers the everyday tasks: start a run, follow its logs, and keep workflows in a repository withduun workflows diffandduun workflows apply.
To be told when something happens instead of polling, add a webhook endpoint.
Resources
| Resource | What it covers |
|---|---|
| Runs | Start runs, follow logs, resolve asks, pause, cancel and restart |
| Factories | A team’s pipeline: workflows, repos and guardrails |
| Workflows | Workflow configs, versions, diffs, restores and test runs |
| Agents | Built-in and custom agents |
| Skills | Workspace skills (SKILL.md) and publishing to Explore |
| Commands | Slash commands and their bindings |
| Webhook endpoints | Outgoing endpoints, deliveries and incoming trigger URLs |
| Usage and budgets | Spend reports, credit balance and budgets |