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/v1

All 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

  1. Open Settings → API keys & secrets and go to Duun API keys.
  2. Select New API key, give it a name that says where it runs (for example ci-github-actions), and pick its scopes.
  3. 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.

ScopeAllows
runs:readList and read runs, their asks and their logs
runs:writeStart, cancel, pause, resume and restart runs; resolve asks
factories:readList and read factories
factories:writeCreate, update, pause, resume and archive factories
workflows:readRead workflows and their versions
workflows:writeCreate workflows, apply versions, restore, test, pause and resume
agents:readList and read agents
agents:writeCreate, update and delete custom agents
skills:readList and read workspace skills
skills:writeCreate, update, delete and publish skills
commands:readList and read slash commands
commands:writeCreate, update and delete slash commands
webhooks:readList webhook endpoints, deliveries and trigger URLs
webhooks:writeCreate, update, rotate and delete webhook endpoints and trigger URLs
usage:readRead 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-01

Without 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 uses multipart/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 id with a type prefix and an object field naming its type.
  • Fields with no value are null, not omitted.
PrefixObject
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_8Kc2Vd91TfQx

Error 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)
Response
{
  "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 duun CLI covers the everyday tasks: start a run, follow its logs, and keep workflows in a repository with duun workflows diff and duun workflows apply.

To be told when something happens instead of polling, add a webhook endpoint.

Resources

ResourceWhat it covers
RunsStart runs, follow logs, resolve asks, pause, cancel and restart
FactoriesA team’s pipeline: workflows, repos and guardrails
WorkflowsWorkflow configs, versions, diffs, restores and test runs
AgentsBuilt-in and custom agents
SkillsWorkspace skills (SKILL.md) and publishing to Explore
CommandsSlash commands and their bindings
Webhook endpointsOutgoing endpoints, deliveries and incoming trigger URLs
Usage and budgetsSpend reports, credit balance and budgets

    Type to search the docs, help center and blog.