> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Platform API

> Use the Duvo Developer Platform API to start runs, manage agents, review cases, and integrate Duvo into your own code, scripts, and pipelines.

The Duvo Developer Platform API lets you drive Duvo from your own code, scripts, and pipelines. Use it to automate core team workflows and integrate Duvo with the systems your team already runs on.

With the API, you can:

* Start Runs
* Manage Agents
* Review Cases
* Move Files in and out of Duvo
* Manage Connections

## Authentication

The API authenticates requests with an API key.

1. Generate a key in the Duvo dashboard at [Your Profile → API keys](https://app.duvo.ai/settings/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](https://app.duvo.ai/settings/api-keys).
2. Send the key as a bearer token on every request:

   ```
   Authorization: Bearer <your-api-key>
   ```

API keys are scoped to a single team or to all teams the owner can access, and inherit the permissions of the user who generated them.

## Base URL and versioning

The current version of the API is **v2**. All endpoints are served under:

```
https://api.duvo.ai/v2
```

The paths in the tables below are shown relative to that prefix. Team-scoped endpoints include your team ID in the path (`/teams/{teamId}/...`); list the teams your key can act on with `GET /teams`. Endpoints exposed as MCP tools are listed in [Available MCP Tools](/mcp/available-tools).

<Note>
  **v1 is deprecated** and will be sunset on **15 June 2026** — new integrations
  should target `/v2`.
</Note>

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