Developer Platform API

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.

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>

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. See Platform behaviors to plan for for team-scoped Connections, Agent Memory, and team settings behavior.

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 schema rules

Case schemas use a supported subset of JSON Schema. The root must have "type": "object", and every object schema, including nested objects, must set "additionalProperties": false. Otherwise the request fails with a 400 error: Object schemas must set additionalProperties to false. Every array schema must define items.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string" }
        }
      }
    }
  }
}

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`	Probe a connection’s tool catalog
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

On the probe endpoint, a success: false response includes a code: listing_unavailable means there’s nothing to list yet for that connection (not an error — some connections only expose tools once connected), while probe_failed means the probe genuinely failed.

Provider keys vs integration types

The native OAuth {provider} path parameter is a provider key, not an integration type. Use oauth_provider_key from listIntegrations or duvo integrations list --json; those are the source of truth, and this reference table may lag.

Provider key	Integration type	Name
`google_gmail`	`gmail`	Google Gmail
`google_sheets`	`googlesheets`	Google Sheets
`google_docs`	`googledocs`	Google Docs
`google_drive`	`googledrive`	Google Drive
`google_calendar`	`googlecalendar`	Google Calendar
`slack`	`slack`	Slack
`microsoft_outlook`	`outlook`	Microsoft Outlook
`microsoft_calendar`	`microsoft-calendar`	Microsoft Calendar
`microsoft_excel`	`excel`	Microsoft Excel
`microsoft_word`	`word`	Microsoft Word
`microsoft_teams`	`teams`	Microsoft Teams
`microsoft_sharepoint`	`sharepoint`	SharePoint
`microsoft_onedrive`	`onedrive`	OneDrive
`microsoft_powerbi`	`powerbi`	Microsoft Power BI
`salesforce`	`salesforce`	Salesforce
`pipedrive`	`pipedrive`	Pipedrive
`linear-native`	`linear-native`	Linear
`confluence`	`confluence`	Confluence
`jira`	`jira`	Jira
`saps4hana`	`saps4hana`	SAP S/4HANA
`intercom`	`intercom`	Intercom
`zendesk`	`zendesk`	Zendesk
`shopify`	`shopify`	Shopify

SAP S/4HANA start requests also require name, sap-host, and sap-client-id; Intercom requires intercom-region; Zendesk requires subdomain. Shopify requires shop as a bare <store>.myshopify.com host (for example, acme.myshopify.com), without a scheme or path.

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 the schedules you own on an Agent
GET	`/agents/{agent_id}/schedules/all`	List every member’s schedules on an Agent (elevated team role)
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

GET /agents/{agent_id}/schedules returns only the schedules the calling key’s user owns, whatever that user’s role. GET /agents/{agent_id}/schedules/all is the carve-out for elevated team roles: it returns every team member’s schedules on the Agent, each row carrying the user_name and user_email of the member who created it. A caller without an elevated role receives 403. The all-users response is bounded, so it also carries a truncated boolean. It is false for every Agent within normal usage. When it is true, the Agent has more schedules than one response can carry, the rows returned are the oldest by created_at, and the rest are omitted — check it before treating the list as a complete audit.

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 an automation 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

​Authentication

​Base URL and versioning

​Endpoints

​Agents

​Setups

​Runs

​Files

​Cases and Queues

​Case Labels

​Case schema rules

​Case Triggers

​Connections

​Provider keys vs integration types

​Skills

​Secrets and Logins

​Schedules

​Memory

​Sandboxes

​Setup Configuration

​Plugins

​Team

​Process Intelligence

Authentication

Base URL and versioning

Endpoints

Agents

Setups

Runs

Files

Cases and Queues

Case Labels

Case schema rules

Case Triggers

Connections

Provider keys vs integration types

Skills

Secrets and Logins

Schedules

Memory

Sandboxes

Setup Configuration

Plugins

Team

Process Intelligence