Duvo API Reference
Base URL: https://api.duvo.ai
The Duvo API lets Duvo workspaces start and inspect agent runs, create queue cases, respond to human approval gates, manage sandboxed execution, and connect external systems. API access is available to any Duvo workspace, including the self-serve Free plan at https://app.duvo.ai.
Machine-Readable Specification
- OpenAPI: https://www.duvo.ai/openapi.json
- Well-known OpenAPI: https://www.duvo.ai/.well-known/openapi.json
- These routes proxy the live Duvo Public API specification and are the source of truth for the full endpoint list, schemas, operation IDs, security schemes, and response models.
Authentication
Send an API key or an OAuth access token as Authorization: Bearer <token>. A credential acts as the Duvo user it belongs to, with that user's role in each team. Duvo has no per-endpoint API scopes. See /auth.md for both methods and their limits.
Selected Endpoint Families
This markdown file is a quick orientation, not the exhaustive API reference. Use the OpenAPI specification above before generating clients or calling endpoints.
POST /v2/teams/{team_id}/agents: Create or register an agent worker.POST /v2/teams/{team_id}/runs: Start an agent run from an agent, queue case, file, webhook, schedule, or external application.GET /v2/runs/{run_id}: Inspect run status, owner, timestamps, and outcome.GET /v2/runs/{run_id}/messages: Read run messages, tool calls, files, approvals, and audit events.POST /v2/runs/{run_id}/human-requests/{request_id}/respond: Approve, reject, or answer a human gate.POST /v2/queues/{queue_id}/cases: Create a durable case for an agent or queue consumer.POST /v2/teams/{team_id}/artifacts: Create an Operating Insights dashboard from a prompt; refine, refresh, publish, and export it under/v2/artifacts/{artifact_id}.GET /v2/agent/{agent_id}/runs/{run_id}/evaluation: Read the automatic evaluation of a run: each rubric's verdict, severity, and reason.POST /v2/sandboxes: Request a governed sandbox for browser, file, or desktop execution.POST /v2/mcp: Connect to the hosted MCP endpoint from any Duvo workspace.
Errors
Errors are JSON with a human-readable error string. Some also carry a message with more detail, and a few carry other fields. Duvo has no stable machine-readable error code yet, so branch on the HTTP status:
- 400: the request is invalid. Fix it before sending it again.
- 401: the credential is missing, expired, revoked or not recognised. Sign in again or use a valid API key.
- 403: the user's role, team membership or plan does not allow the action. Retrying does not help.
- 404: the resource does not exist, or it belongs to a team the credential cannot act on.
- 409: the resource is in a state that does not allow the change, for example answering a human request while the run is still executing.
- 429: rate limited. Wait the number of seconds in
Retry-After, then retry. - 5xx: a Duvo error. Read the current state before you retry a write.
Agent Retry Guidance
- Duvo does not deduplicate retried writes and has no idempotency key header. Retrying
POST /v2/teams/{team_id}/runsstarts another run, and retryingPOST /v2/queues/{queue_id}/casescreates the cases again. After a timeout or an ambiguous result, read the current state before you retry. - Starting a run returns 201 with the new run. Poll
GET /v2/runs/{run_id}untilcompleted_atis set, or until the status iswaitingfor a human response. To be called back instead, passwebhook_urlwhen you start the run (see /webhooks.md). - Requests are rate limited per API key, and per client IP address for requests without one, such as OAuth calls. Every response states the policy in
RateLimit-Policyand the remaining quota inRateLimit, also sent asratelimit-limit,ratelimit-remainingandratelimit-reset. Slow down before the quota runs out, and on a 429 wait forRetry-After. - Honor
DeprecationandSunsetheaders when present.
Machine-readable source:
https://www.duvo.ai/api-reference.md