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 abuild 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:- Native OAuth (Gmail, Google Sheets, Outlook, Google Calendar, etc.) — Use Start Native OAuth Connection
- Custom MCP with OAuth — Use Start MCP OAuth Connection
- User-provided credentials (Snowflake, Tableau, custom MCP with API keys) — Use Create a Connection
List Connections
Returns the authenticated user’s connections for the current team. Filter by integration type with thetype 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 withPOST /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(andoauth_client_secret, unless it is a public PKCE-only client). A request that passesoauth_client_idtogether withcustom_integration_idis refused with400. - Catalog integration: the
oauth_client_idin 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.
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 customserver_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.