# Duvo API Reference

Base URL: https://api.duvo.ai

The Duvo API lets approved customer workspaces start and inspect agent runs, create queue cases, respond to human approval gates, manage sandboxed execution, and connect external systems. API access requires a provisioned workspace.

## Machine-Readable Specification

- OpenAPI: https://www.duvo.ai/openapi.json
- Well-known OpenAPI: https://www.duvo.ai/.well-known/openapi.json

## Authentication

Use workspace-issued bearer credentials. Enterprise workspaces can use scoped OAuth client credentials where enabled. See /auth.md for scopes, token handling, and access constraints.

## Core Endpoints

- POST /v1/agents: Create or register an assignment-backed agent worker.
- POST /v1/runs: Start an agent run from an assignment, queue case, file, webhook, schedule, or external application.
- GET /v1/runs/{run_id}: Inspect run status, owner, timestamps, and outcome.
- GET /v1/runs/{run_id}/messages: Read run messages, tool calls, files, approvals, and audit events.
- POST /v1/runs/{run_id}/human-requests/{request_id}/respond: Approve, reject, or answer a human gate.
- POST /v1/queues/{queue_id}/cases: Create a durable case for an assignment or queue consumer.
- POST /v1/sandboxes: Request a governed sandbox for browser, file, or desktop execution.
- POST /v1/mcp: Connect to the hosted MCP endpoint for approved workspaces.

## Errors

API errors should return JSON with code, message, request_id, and optional details. Clients should treat 401 as missing/expired credentials, 403 as insufficient workspace scope or policy, 404 as missing workspace-owned resource, 409 as state conflict, and 429 as a retryable rate limit response when Retry-After is present.

## Agent Retry Guidance

- Mutating requests should include an Idempotency-Key header when retry safety matters.
- 202 Accepted responses represent asynchronous work. Poll GET /v1/runs/{run_id} until the run reaches completed, failed, or canceled.
- Clients should honor RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After, Deprecation, and Sunset headers when present.