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
• 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

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.

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 /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/: Inspect run status, owner, timestamps, and outcome.
• GET /v1/runs//messages: Read run messages, tool calls, files, approvals, and audit events.
• POST /v1/runs//human-requests//respond: Approve, reject, or answer a human gate.
• POST /v1/queues//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/ 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.