API reference

REST API

The DunOps REST API gives you programmatic access to workspaces, runs, playbooks, and providers.

Base URL

bash

https://api.dunops.com/v1

All endpoints are versioned. The current stable version is v1. Pass DunOps-Version: 2026-01-01 to pin to a specific release and avoid breaking changes from future updates.

Common patterns

Pattern	Description
`GET /workspaces/me`	Return the authenticated workspace
`GET /playbooks`	List all playbooks in the workspace
`POST /playbooks/:id/runs`	Trigger a playbook run
`GET /runs/:id`	Poll the status of a run
`GET /providers`	List connected providers

All list endpoints return a data array and a meta object with total, page, and per_page.

Example: trigger a playbook run

bash

# Trigger a playbook run
curl -X POST https://api.dunops.com/v1/playbooks/pb_1234/runs \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"branch": "main", "environment": "production"}}'

# Poll the run status
curl https://api.dunops.com/v1/runs/run_5678 \
  -H "Authorization: Bearer dk_live_..."

Run response (excerpt)

{
  "id": "run_5678",
  "status": "running",
  "playbook_id": "pb_1234",
  "started_at": "2026-06-17T12:00:00Z",
  "steps": [
    { "id": "step_1", "status": "succeeded", "capability": "vercel.create-deployment" },
    { "id": "step_2", "status": "waiting_approval" }
  ]
}

Error responses

Status	Meaning
`400`	Bad request — check the request body
`401`	Invalid or missing API key
`403`	Key lacks permission for this action
`404`	Resource not found
`429`	Rate limit exceeded — see Rate limits
`500`	DunOps internal error — transient, safe to retry

Next steps

Authentication →

How to generate and use API keys.

Webhooks →

Push events from DunOps to your systems.

Rate limits →

How many requests you can make per minute.