# Duvo API

> Scoped agent-readable index for the Duvo REST API. Base URL https://api.duvo.ai. Workspace-scoped access required.

## API Resources

- [OpenAPI specification](https://www.duvo.ai/openapi.json): Live OpenAPI specification for all public Duvo API endpoints.
- [API reference markdown](https://www.duvo.ai/api-reference.md): Markdown API reference with endpoints, authentication, and error behavior.
- [Authentication guide](https://www.duvo.ai/auth.md): Auth, access, scopes, tenant controls, and credential handling.
- [Webhooks guide](https://www.duvo.ai/webhooks.md): Webhook delivery, retry, signature, and event guidance.

## Selected Endpoint Families

- `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.

## Authentication

- [Auth guide](https://www.duvo.ai/auth.md): Workspace bearer tokens, OAuth client credentials, scopes, RBAC, and SSO.
- Send credentials as `Authorization: Bearer <token>`.
- Include `Idempotency-Key` on mutating requests when retry safety matters.

## Optional

- [Webhooks guide](https://www.duvo.ai/webhooks.md): Event delivery, retries, HMAC signature verification.
- [MCP guide](https://www.duvo.ai/mcp.md): Hosted and custom MCP integration patterns.