Skip to content

Duvo API Reference.

Duvo REST API reference: agent runs, queue cases, human approvals, files, sandboxes, MCP, and webhooks for production agent workloads.

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

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}/runs starts another run, and retrying POST /v2/queues/{queue_id}/cases creates 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} until completed_at is set, or until the status is waiting for a human response. To be called back instead, pass webhook_url when 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-Policy and the remaining quota in RateLimit, also sent as ratelimit-limit, ratelimit-remaining and ratelimit-reset. Slow down before the quota runs out, and on a 429 wait for Retry-After.
  • Honor Deprecation and Sunset headers when present.

Machine-readable source:

https://www.duvo.ai/api-reference.md