Skip to main content
The Duvo Public API lets you create and manage Agents and Revisions programmatically, so you can provision them from your own scripts, CI/CD pipelines, or automation tools instead of the Duvo web interface. For authentication, rate limiting, and error handling details, see Running Agents via API.

Key Concepts

Agents represent a configured worker with a specific AOP, connections, and capabilities. Each Agent can have multiple Revisions. Revisions are versioned Setup snapshots for an Agent. A Revision captures the AOP, model settings, and connected skills at a specific time. When a Run is started, it always uses the Agent’s latest Revision. You can create an Agent and its first Revision in a single request, or manage them separately.

Endpoints

Agents

List Agents

API: GET /teams/{teamId}/agents — see the API Reference for full details.

Create an Agent

Creates a new Agent. You can optionally include a build object in the request body to create the first Revision in the same call, saving you a separate request.
API: POST /teams/{teamId}/agents — see the API Reference for full details.

Get an Agent

API: GET /agents/{agent_id} — see the API Reference for full details.

Update an Agent

API: PATCH /agents/{agent_id} — see the API Reference for full details.

Revisions

Get a Revision

API: GET /agents/{agent_id}/revisions/{build_id} — see the API Reference for full details.

List Revisions for an Agent

API: GET /agents/{agent_id}/revisions — see the API Reference for full details.

Create a Revision

Creates a new Revision for an existing Agent. Use this when you want to deploy Setup changes to an Agent that already exists.
API: POST /agents/{agent_id}/revisions — see the API Reference for full details.

Update a Revision

API: PATCH /revisions/{build_id} — see the API Reference for full details.

Folders

Agents can be organized into folders. Folders are managed via the API and reflected in the Duvo web interface.

List Folders

API: GET /teams/{teamId}/agent-folders — see the API Reference for full details.

Create a Folder

API: POST /teams/{teamId}/agent-folders — see the API Reference for full details.

Update a Folder

API: PATCH /agent-folders/{folder_id} — see the API Reference for full details.

Delete a Folder

API: DELETE /agent-folders/{folder_id} — see the API Reference for full details.

Move Agents into a Folder

API: POST /teams/{teamId}/agent-folders/move-agents — see the API Reference for full details.

Connections

Connections represent OAuth accounts or credentials that your agents use to access external services. You can manage existing connections and create new ones programmatically. Connection types and how to create them:

List Connections

Returns the authenticated user’s connections for the current team. Filter by integration type with the type query parameter.
API: GET /teams/{teamId}/connections — see the API Reference for full details.

Get a Connection

API: GET /connections/{connection_id} — see the API Reference for full details.

Get Connection Credentials

Returns the credential field names configured for a connection. Sensitive values (API keys, tokens, passwords) are returned as empty strings — the response only shows which fields are set, not their values.
API: GET /connections/{connection_id}/credentials — see the API Reference for full details.

Create a Connection

Creates a user-provided connection with optional credential headers. A Connection to a custom MCP server is made through a custom integration: register the server once with POST /teams/{teamId}/integrations/custom (Manager role or above), then pass its ID as custom_integration_id. A custom MCP connection without custom_integration_id is refused with 400. For OAuth-based connections (native providers or OAuth MCP servers), use the dedicated OAuth endpoints below instead.
API: POST /teams/{teamId}/connections — see the API Reference for full details.

Update a Connection

API: PATCH /connections/{connection_id} — see the API Reference for full details.

Delete a Connection

API: DELETE /connections/{connection_id} — see the API Reference for full details.

Start Native OAuth Connection

Starts an OAuth flow for a native provider. The {provider} path parameter is a provider key, not an integration type. listIntegrations and duvo integrations list --json (field oauth_provider_key) are the source of truth; the table below can lag. Returns an authorization URL you redirect the user’s browser to. Once they grant consent, Duvo creates the connection and redirects to your optional return_url. Poll List Connections to detect when the new connection appears. SAP S/4HANA start requests 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. For further details, see Provider keys vs integration types.
API: POST /teams/{teamId}/connections/oauth/native/{provider}/start — see the API Reference for full details.

Start MCP OAuth Connection

Starts an OAuth flow for an MCP server. Returns an authorization URL the user must open in a browser. Once they grant consent, Duvo creates the connection. Which OAuth client Duvo uses depends on the connection:
  • Custom MCP server: the client stored on the custom integration. Register it there with oauth_client_id (and oauth_client_secret, unless it is a public PKCE-only client). A request that passes oauth_client_id together with custom_integration_id is refused with 400.
  • Catalog integration: the oauth_client_id in the request if you pass one, such as the client from a NetSuite Integration record; otherwise a client Duvo has preregistered for that integration, such as HubSpot or Asana.
  • Reconnect: a connection made with your own client reuses its stored client when you omit oauth_client_id.
When none of these supplies a client, Duvo registers itself through Dynamic Client Registration (RFC 7591). Only in that case, use Check MCP OAuth Support first to confirm the server supports it. For a custom MCP server, pass the custom_integration_id of the custom integration registered for it; a new connection to a custom MCP server without one is refused with 400. A catalog integration such as NetSuite or Asana takes integration_type instead. To re-authorize an existing connection, pass reconnect_instance_id and, if the connection was made through a custom integration, its custom_integration_id.
API: POST /teams/{teamId}/connections/oauth/mcp/start — see the API Reference for full details.

Check MCP OAuth Support

Probes an MCP server URL to check whether it supports OAuth Dynamic Client Registration. Returns the authorization endpoint and required scopes when supported. Performs no writes — use this as a pre-flight check before calling Start MCP OAuth Connection.
API: POST /connections/oauth/mcp/check — see the API Reference for full details.

Probe MCP Server

Tests a connection’s tool catalog and returns the list of tools it exposes. Pass a custom server_url (and optional headers) to validate your own MCP server before creating a connection, or pass a catalog integration_slug to probe one of Duvo’s built-in connections — the backend resolves the server URL for you. A success: false response includes a code: listing_unavailable means there’s nothing to list yet for that connection (not an error — some connections, such as remote MCP servers that require an OAuth/DCR handshake or vendor-hosted catalogs like GitHub and Linear, only expose tools once connected), while probe_failed means the probe genuinely failed (unreachable server, rejected credentials, etc.).
API: POST /teams/{teamId}/connections/mcp/probe — see the API Reference for full details.

Schedules

List Schedules for an Agent

API: GET /agents/{agent_id}/schedules — see the API Reference for full details.

Complete Example

This example creates an Agent with its first Revision in a single request, then starts a Run on it.
For more details on starting and monitoring Runs, see Running Agents via API.