- Start Runs
- Manage Agents
- Review Cases
- Move Files in and out of Duvo
- Manage Connections
Authentication
The API authenticates requests with an API key.- Generate a key in the Duvo dashboard at Your Profile → API keys. Choose whether the key is scoped to a single team or works across all teams you can access. Users with the Manager role or above can also create keys for a specific team at Team Settings → API keys.
-
Send the key as a bearer token on every request:
Authorization: Bearer <your-api-key>
Base URL and versioning
The current version of the API is v2. All endpoints are served under:https://api.duvo.ai/v2
/teams/{teamId}/...); list the teams your key can act on with GET /teams. Endpoints exposed as MCP tools are listed in Available MCP Tools.
v1 is deprecated and will be sunset on 15 June 2026 — new integrations
should target
/v2.Endpoints
Agents
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/agents | List Agents for your team |
| POST | /teams/{teamId}/agents | Create a new Agent |
| GET | /agents/{agent_id} | Get an Agent by ID |
| PATCH | /agents/{agent_id} | Update an Agent |
| DELETE | /agents/{agent_id} | Delete an Agent |
| GET | /teams/{teamId}/agent-folders | List Agent folders |
| POST | /teams/{teamId}/agent-folders | Create a folder |
| PATCH | /agent-folders/{folder_id} | Rename or move a folder |
| DELETE | /agent-folders/{folder_id} | Delete a folder |
| POST | /teams/{teamId}/agent-folders/move-agents | Move Agents into a folder |
Setups
| Method | Path | Description |
|---|---|---|
| GET | /agents/{agent_id}/revisions | List Setups for an Agent |
| POST | /agents/{agent_id}/revisions | Create a new Setup |
| GET | /agents/{agent_id}/revisions/{build_id} | Get a Setup by ID |
| PATCH | /revisions/{build_id} | Update a Setup |
| POST | /revisions/{build_id}/promote | Promote a Setup to live |
Runs
| Method | Path | Description |
|---|---|---|
| GET | /runs | List Runs for your team |
| POST | /runs | Start a new Run |
| GET | /runs/{run_id} | Get a Run’s status |
| GET | /runs/{run_id}/messages | List messages from a Run |
| POST | /runs/{run_id}/messages | Send a message to an active Run |
| POST | /runs/{run_id}/human-requests/{request_id}/respond | Respond to a human-in-the-loop request |
| POST | /runs/{run_id}/stop | Stop an active Run |
Files
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/files | List Files for your team |
| POST | /teams/{teamId}/files/create-upload-url | Generate a signed upload URL |
| GET | /teams/{teamId}/files/content/{path} | Get a file’s text content |
| PUT | /teams/{teamId}/files/content/{path} | Update a file’s text content |
| GET | /teams/{teamId}/files/download-url/{path} | Generate a signed download URL |
| PATCH | /teams/{teamId}/files | Rename a file |
| DELETE | /teams/{teamId}/files/{path} | Delete a file |
Cases and Queues
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/queues | List queues |
| POST | /teams/{teamId}/queues | Create a queue |
| GET | /queues/{queue_id} | Get a queue |
| PATCH | /queues/{queue_id} | Update a queue |
| DELETE | /queues/{queue_id} | Delete a queue |
| GET | /queues/{queue_id}/agents | List Agents bound to a queue |
| GET | /queues/{queue_id}/cases | List cases in a queue |
| POST | /queues/{queue_id}/cases/search | Search cases |
| POST | /queues/{queue_id}/cases | Create cases |
| DELETE | /queues/{queue_id}/cases | Delete every case in a queue (destructive) |
| POST | /queues/{queue_id}/cases/bulk-reprocess | Re-process cases on a queue consumer Agent |
| POST | /queues/{queue_id}/cases/bulk-update-status | Update the status of multiple cases |
| POST | /queues/{queue_id}/cases/bulk-delete | Delete a batch of cases |
| GET | /cases/{case_id} | Get a case |
| DELETE | /cases/{case_id} | Delete a case |
| GET | /cases/{case_id}/runs | List Runs for a case |
| GET | /cases/{case_id}/runs/{run_id}/recent-messages | Get recent messages from a case Run |
Case Labels
| Method | Path | Description |
|---|---|---|
| GET | /queues/{queue_id}/labels | List labels in a queue |
| POST | /queues/{queue_id}/labels | Create a label |
| PATCH | /queues/{queue_id}/labels/{label_id} | Update a label |
| DELETE | /queues/{queue_id}/labels/{label_id} | Delete a label |
| GET | /queues/{queue_id}/cases/{case_id}/labels | List labels on a case |
| POST | /queues/{queue_id}/cases/{case_id}/labels | Assign labels to a case |
| POST | /queues/{queue_id}/cases/{case_id}/labels/unlink | Remove labels from a case |
Case Triggers
| Method | Path | Description |
|---|---|---|
| GET | /agents/{agent_id}/case-triggers | List case triggers |
| POST | /agents/{agent_id}/case-triggers | Create a case trigger |
| GET | /agents/{agent_id}/case-triggers/{trigger_id} | Get a case trigger |
| PATCH | /agents/{agent_id}/case-triggers/{trigger_id} | Update a case trigger |
| DELETE | /agents/{agent_id}/case-triggers/{trigger_id} | Delete a case trigger |
| GET | /agents/{agent_id}/case-triggers/conflict-preview | Preview trigger conflicts |
Connections
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/integrations | List available connection types |
| POST | /teams/{teamId}/integrations/custom | Register a custom MCP server |
| DELETE | /integrations/custom/{custom_integration_id} | Remove a custom MCP server |
| GET | /teams/{teamId}/connections | List authorized Connections |
| POST | /teams/{teamId}/connections | Create a Connection |
| GET | /connections/{connection_id} | Get a Connection |
| PATCH | /connections/{connection_id} | Update a Connection |
| DELETE | /connections/{connection_id} | Remove a Connection |
| GET | /connections/{connection_id}/credentials | Get the header keys configured for a Connection |
| POST | /teams/{teamId}/connections/mcp/probe | Test connectivity to an MCP server URL |
| POST | /teams/{teamId}/connections/oauth/native/{provider}/start | Start a native OAuth flow (Gmail, Google Sheets, Outlook, etc.) |
| POST | /teams/{teamId}/connections/oauth/mcp/start | Start an OAuth flow for a remote MCP server |
| POST | /connections/oauth/mcp/check | Check whether an MCP server supports OAuth Dynamic Client Registration |
Skills
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/skills | List Skills for your team |
| GET | /skills/system | List system-wide Skills |
| POST | /teams/{teamId}/skills | Create or update a Skill from JSON |
| POST | /teams/{teamId}/skills/upload | Create or update a Skill by uploading a SKILL.md file or ZIP archive |
| GET | /skills/{skill_id}/files | List files in a Skill |
| GET | /skills/{skill_id}/files/{path} | Get a Skill file’s content |
| PUT | /skills/{skill_id}/files/{path} | Update a Skill file |
| GET | /skills/{skill_id}/download | Download a Skill archive |
| DELETE | /skills/{skill_id} | Delete a Skill |
| GET | /skills/{skill_id}/assignments | List Agents using a Skill |
Secrets and Logins
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/credentials | List stored secrets |
| POST | /teams/{teamId}/credentials | Create a secret |
| GET | /credentials/{id} | Get a secret |
| PATCH | /credentials/{id} | Update a secret |
| DELETE | /credentials/{id} | Delete a secret |
| GET | /teams/{teamId}/browser-agent/credentials/{userId} | List stored Logins |
| POST | /teams/{teamId}/browser-agent/credentials/{userId} | Create a Login |
| GET | /teams/{teamId}/browser-agent/credentials/{userId}/{id} | Get a Login |
| PATCH | /teams/{teamId}/browser-agent/credentials/{userId}/{id} | Update a Login |
| DELETE | /teams/{teamId}/browser-agent/credentials/{userId}/{id} | Delete a Login |
Schedules
| Method | Path | Description |
|---|---|---|
| GET | /agents/{agent_id}/schedules | List schedules configured for an Agent |
| POST | /agents/{agent_id}/schedules | Create a schedule for an Agent |
| PATCH | /agents/{agent_id}/schedules/{schedule_id} | Update a schedule |
| DELETE | /agents/{agent_id}/schedules/{schedule_id} | Delete a schedule |
Memory
| Method | Path | Description |
|---|---|---|
| GET | /agents/{agent_id}/memory/files | List an Agent’s memory files |
| GET | /agents/{agent_id}/memory/files/{path} | Get a single memory file’s content |
Sandboxes
| Method | Path | Description |
|---|---|---|
| POST | /sandboxes | Create a new sandbox environment |
| POST | /sandboxes/{sandbox_id}/upload-urls | Generate a signed URL to upload files into a sandbox |
| GET | /sandboxes/{sandbox_id}/files | List files in a sandbox directory |
| POST | /sandboxes/{sandbox_id}/files | Upload a file directly to a sandbox |
Setup Configuration
These endpoints attach Connections, Logins, and Secrets to a specific Setup (revision).| Method | Path | Description |
|---|---|---|
| GET | /agents/{agent_id}/revisions/{build_id}/integrations | List Connections attached to a Setup |
| POST | /agents/{agent_id}/revisions/{build_id}/integrations | Attach one or more Connections to a Setup |
| DELETE | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id} | Remove a Connection from a Setup |
| GET | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/connections | List Connection instances for a Connection slot |
| POST | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/connections | Pin a specific Connection to a Connection slot |
| DELETE | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/connections/{connection_id} | Unpin a Connection from a Connection slot |
| GET | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/queues | List queues for a Connection slot |
| PUT | /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/queues | Replace the queues for a Connection slot |
| GET | /agents/{agentId}/revisions/{buildId}/logins | List Logins attached to a Setup |
| POST | /agents/{agentId}/revisions/{buildId}/logins | Attach a Login to a Setup |
| DELETE | /agents/{agentId}/revisions/{buildId}/logins/{exposedCredentialId} | Remove a Login from a Setup |
| GET | /agents/{agentId}/revisions/{buildId}/credentials | List Secrets attached to a Setup |
| POST | /agents/{agentId}/revisions/{buildId}/credentials | Attach a Secret to a Setup |
| DELETE | /agents/{agentId}/revisions/{buildId}/credentials/{credentialId} | Remove a Secret from a Setup |
Plugins
| Method | Path | Description |
|---|---|---|
| GET | /plugins/catalog | List built-in plugins that can be referenced in a Setup |
Team
| Method | Path | Description |
|---|---|---|
| GET | /teams | List teams your API key can act on |
| GET | /teams/{teamId} | Get your team’s details |
| GET | /teams/{teamId}/members | List team members |
| GET | /profile | Get your user profile |
Process Intelligence
| Method | Path | Description |
|---|---|---|
| GET | /teams/{teamId}/clarity-v2/processes | List process captures for your team |
| GET | /clarity-v2/processes/{process_id} | Get a process capture by ID |
| GET | /clarity-v2/processes/{process_id}/snapshots/{kind} | List process snapshots of one kind |
| GET | /clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id} | Get a process snapshot |
| POST | /clarity-v2/processes/{process_id}/snapshots/{kind}/save | Save user edits as the live snapshot |
| POST | /clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id}/promote | Promote a snapshot to live |
| DELETE | /clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id} | Archive a snapshot |
| POST | /clarity-v2/processes/{process_id}/snapshots/{kind}/generate | Generate a snapshot from captures |
| POST | /clarity-v2/processes/{process_id}/snapshots/{kind}/stop | Stop a running snapshot generation |
| POST | /clarity-v2/processes/{process_id}/automation | Build an Agent from a transformation proposal |
| POST | /clarity-v2/processes/{process_id}/postprocess | Re-run postprocessing on an existing snapshot |
| POST | /clarity-v2/processes/{process_id}/invite-link | Create or regenerate an interview invite link |
| POST | /clarity-v2/processes/{process_id}/artifact-imports/create-upload-url | Create a signed upload URL for an artifact import |
| POST | /clarity-v2/processes/{process_id}/artifact-imports/{capture_id}/complete | Complete an artifact import |
| POST | /clarity-v2/processes/{process_id}/artifact-chat/messages | Send an artifact-chat message and start a turn |
| PUT | /clarity-v2/processes/{process_id}/artifact-chat/messages/{message_id} | Accept or decline an artifact-chat patch proposal |
| GET | /clarity-v2/processes/{process_id}/transformation-proposals/{transformation_proposal_id}/extra-capture-requests | List pending extra capture requests for a process |
| PATCH | /clarity-v2/processes/{process_id}/transformation-proposals/{transformation_proposal_id}/extra-capture-requests/{request_id}/assign | Assign an extra capture request |