Connections

Manage your connected integrations

get

List the authenticated user's connections (connected integration instances) for the current team. Includes team-shared instances visible to the caller when the org-level Connections sharing setting is on. Filter by integration type with the type query parameter.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Query parameters

typestringOptional

limitinteger · min: 1 · max: 100OptionalDefault: 100

offsetinteger · max: 9007199254740991Optional

Responses

200

Default Response

application/json

totalinteger · max: 9007199254740991Required

limitinteger · min: 1 · max: 9007199254740991Required

offsetinteger · max: 9007199254740991Required

401

Default Response

application/json

500

Default Response

application/json

get

/v1/connections

HTTPcURLJavaScriptPython

GET /v1/connections HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "integrations": [
    {
      "id": "text",
      "name": "text",
      "type": "text",
      "provider": "text",
      "user_id": "text",
      "team_id": "text",
      "server_url": "text",
      "transport_type": "stdio",
      "auth_method": "text",
      "composio_mcp_id": "text",
      "custom_integration_id": "text",
      "icon_url": "text",
      "oauth_provider": "text",
      "oauth_scopes": [
        "text"
      ],
      "has_headers": true,
      "has_oauth_tokens": true,
      "integration_id": "text",
      "shared": true,
      "created_by": "text",
      "created_at": "2026-05-19T22:04:06.939Z",
      "updated_at": "2026-05-19T22:04:06.939Z"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

post

Create a new user-provided connection (custom MCP server) for the current team. OAuth-based integrations (native, composio) require an interactive browser flow — start them with the dedicated OAuth endpoints (/v1/connections/oauth/native/:provider/start, /v1/connections/oauth/mcp/start, or /v1/connections/composio/start) instead of calling this endpoint directly.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

namestring · min: 1Required

server_urlstring · uriOptional

typestringOptionalDefault: custom_mcp

providerstring · enumRequiredPossible values:

auth_methodstring · enumRequiredPossible values:

custom_integration_idstring · uuidOptionalPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Responses

201

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

post

/v1/connections

HTTPcURLJavaScriptPython

POST /v1/connections HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 274

{
  "name": "text",
  "server_url": "https://example.com",
  "type": "custom_mcp",
  "provider": "user",
  "auth_method": "url",
  "custom_integration_id": "123e4567-e89b-12d3-a456-426614174000",
  "headers": {
    "plaintext": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "secret": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }
}

{
  "id": "text",
  "name": "text",
  "type": "text",
  "provider": "text",
  "user_id": "text",
  "team_id": "text",
  "server_url": "text",
  "transport_type": "stdio",
  "auth_method": "text",
  "composio_mcp_id": "text",
  "custom_integration_id": "text",
  "icon_url": "text",
  "oauth_provider": "text",
  "oauth_scopes": [
    "text"
  ],
  "has_headers": true,
  "has_oauth_tokens": true,
  "integration_id": "text",
  "shared": true,
  "created_by": "text",
  "created_at": "2026-05-19T22:04:06.939Z",
  "updated_at": "2026-05-19T22:04:06.939Z"
}

get

Get one of your connections by ID.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

connection_idstring · uuidRequired

Connection ID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Responses

200

Default Response

application/json

idstringRequired

namestringRequired

typestringRequired

providerstringRequired

user_idstring · nullableRequired

team_idstringRequired

server_urlstringOptional

transport_typestring · enumOptionalPossible values:

auth_methodstring · nullableOptional

composio_mcp_idstring · nullableRequiredDefault: null

custom_integration_idstring · nullableOptional

icon_urlstring · nullableOptional

oauth_providerstring · nullableOptional

oauth_scopesstring[] · nullableOptional

has_headersbooleanOptional

has_oauth_tokensbooleanOptional

integration_idstring · nullableOptional

sharedbooleanOptional

created_bystring · nullableOptional

created_atstring · date-timeRequiredPattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updated_atstring · date-timeRequiredPattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/connections/{connection_id}

HTTPcURLJavaScriptPython

GET /v1/connections/{connection_id} HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "type": "text",
  "provider": "text",
  "user_id": "text",
  "team_id": "text",
  "server_url": "text",
  "transport_type": "stdio",
  "auth_method": "text",
  "composio_mcp_id": "text",
  "custom_integration_id": "text",
  "icon_url": "text",
  "oauth_provider": "text",
  "oauth_scopes": [
    "text"
  ],
  "has_headers": true,
  "has_oauth_tokens": true,
  "integration_id": "text",
  "shared": true,
  "created_by": "text",
  "created_at": "2026-05-19T22:04:06.939Z",
  "updated_at": "2026-05-19T22:04:06.939Z"
}

delete

Delete a connection (disconnects the user's connection and removes any triggers bound to it).

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

connection_idstring · uuidRequired

Connection ID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Responses

200

Default Response

application/json

successbooleanRequired

messagestringRequired

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

delete

/v1/connections/{connection_id}

HTTPcURLJavaScriptPython

DELETE /v1/connections/{connection_id} HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "message": "text"
}

patch

Update an existing connection. For sensitive header values, sending an empty string keeps the existing value; send a new value to overwrite. Toggling shared moves the connection between personal and team-shared.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

connection_idstring · uuidRequired

Connection ID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Body

application/json

namestring · min: 1Optional

server_urlstring · uriOptional

auth_methodstring · enumOptionalPossible values:

composio_mcp_idstring · nullableOptional

sharedbooleanOptional

Responses

200

Default Response

application/json

idstringRequired

namestringRequired

typestringRequired

providerstringRequired

user_idstring · nullableRequired

team_idstringRequired

server_urlstringOptional

transport_typestring · enumOptionalPossible values:

auth_methodstring · nullableOptional

composio_mcp_idstring · nullableRequiredDefault: null

custom_integration_idstring · nullableOptional

icon_urlstring · nullableOptional

oauth_providerstring · nullableOptional

oauth_scopesstring[] · nullableOptional

has_headersbooleanOptional

has_oauth_tokensbooleanOptional

integration_idstring · nullableOptional

sharedbooleanOptional

created_bystring · nullableOptional

created_atstring · date-timeRequiredPattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updated_atstring · date-timeRequiredPattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

patch

/v1/connections/{connection_id}

HTTPcURLJavaScriptPython

PATCH /v1/connections/{connection_id} HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "name": "text",
  "server_url": "https://example.com",
  "auth_method": "url",
  "headers": {
    "plaintext": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "secret": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "composio_mcp_id": "text",
  "shared": true
}

{
  "id": "text",
  "name": "text",
  "type": "text",
  "provider": "text",
  "user_id": "text",
  "team_id": "text",
  "server_url": "text",
  "transport_type": "stdio",
  "auth_method": "text",
  "composio_mcp_id": "text",
  "custom_integration_id": "text",
  "icon_url": "text",
  "oauth_provider": "text",
  "oauth_scopes": [
    "text"
  ],
  "has_headers": true,
  "has_oauth_tokens": true,
  "integration_id": "text",
  "shared": true,
  "created_by": "text",
  "created_at": "2026-05-19T22:04:06.939Z",
  "updated_at": "2026-05-19T22:04:06.939Z"
}

get

Get the header keys configured for a connection. Sensitive values (api keys, tokens, passwords) are returned as empty strings — the response only reveals which credential fields are set, never their values.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

connection_idstring · uuidRequired

Connection ID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Responses

200

Default Response

application/json

idstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/connections/{connection_id}/credentials

HTTPcURLJavaScriptPython

GET /v1/connections/{connection_id}/credentials HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

post

Start a Composio-backed connection. Returns a redirect_url the user must open in a browser to complete the OAuth handshake (or null for non-OAuth schemes like API_KEY when the connection finalizes synchronously). After the user completes the flow, call /v1/connections/composio/finalize to provision the corresponding Duvo connection.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

auth_config_idstring · min: 1Required

Composio auth-config ID for the toolkit. Obtain it from Composio's auth-config catalog or by listing existing configs.

callback_urlstring · uriRequired

Where to send the user's browser after they finish the Composio consent screen. Must be an absolute URL.

auth_schemestringOptional

Composio auth scheme (e.g. 'OAUTH2', 'API_KEY', 'BEARER_TOKEN'). Required when supplying non-OAuth credentials in auth_fields.

Responses

200

Default Response

application/json

redirect_urlstring · nullableRequired

Browser URL the user must visit to complete authorization. Null when the connection was completed synchronously (e.g. for API_KEY auth that did not require a browser flow).

statusstring · nullableRequired

Composio connection status (e.g. 'INITIATED', 'ACTIVE', 'FAILED').

connected_account_idstring · min: 1Required

Composio connected-account ID created by this request. Always present — required by /v1/connections/composio/finalize to bind the new connection to the exact account.

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/composio/start

HTTPcURLJavaScriptPython

POST /v1/connections/composio/start HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "auth_config_id": "text",
  "callback_url": "https://example.com",
  "auth_scheme": "text",
  "auth_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "redirect_url": "text",
  "status": "text",
  "connected_account_id": "text"
}

post

Finalize a Composio-backed connection after the start step (/v1/connections/composio/start) has produced a connected_account_id. Provisions a Composio MCP server bound to that account and persists the connection on the team. Works for both OAuth and non-OAuth start flows. Stale or invalid connected_account_id, missing app, or rejected upstream input surfaces as a 4xx via composioErrorFor; only genuinely unexpected upstream/persistence failures return 5xx.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

appstring · min: 1Required

Composio app slug (e.g. 'slack', 'googlesheets'). Must match a Composio toolkit configured for the team.

integration_namestring · min: 1Required

Human-readable name to display for the connection.

connected_account_idstring · min: 1Required

Composio connected-account ID returned by /v1/connections/composio/start. Used to bind this finalize call to the exact account the user just authorized; without it the wrong account could be picked when the team has multiple Composio accounts for the same app.

Responses

201

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/composio/finalize

HTTPcURLJavaScriptPython

POST /v1/connections/composio/finalize HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "app": "text",
  "integration_name": "text",
  "connected_account_id": "text"
}

{
  "integration_id": "text",
  "mcp_url": "text"
}

Probe an MCP server for available tools

post

Probe an MCP server URL and list the tools it exposes. Useful as a dry-run before creating a connection — verifies the URL is reachable, that authentication headers (if any) are correct, and surfaces the tool catalog. Performs no writes; sits alongside /v1/connections/oauth/mcp/check (which probes the same URL for OAuth support).

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

server_urlstring · uriRequired

MCP server URL to test

Responses

200

Default Response

application/json

successbooleanRequired

errorstringOptional

400

Default Response

application/json

401

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/mcp/probe

HTTPcURLJavaScriptPython

POST /v1/connections/mcp/probe HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "server_url": "https://example.com",
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "success": true,
  "tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "error": "text"
}

post

Start an OAuth-based connection with a native provider (Gmail, Google Sheets, Outlook, etc.). Returns an authorization URL that must be opened in a browser by a human end-user; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional return_url (or the Duvo dashboard if none is provided). Poll /v1/connections to detect the new connection.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

providerstringRequired

OAuth provider slug (e.g. 'google', 'gmail', 'googlesheets', 'outlook'). Must match a configured native OAuth provider.

Body

application/json

return_urlstringOptional

Where to send the user's browser after OAuth completes.

Other propertiesstringOptional

Responses

200

Default Response

application/json

authorization_urlstringRequired

OAuth provider authorization URL to open in a browser

401

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/oauth/native/{provider}/start

HTTPcURLJavaScriptPython

POST /v1/connections/oauth/native/{provider}/start HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "return_url": "text",
  "ANY_ADDITIONAL_PROPERTY": "text"
}

{
  "authorization_url": "text"
}

post

Start an OAuth-based connection with a remote MCP server using Dynamic Client Registration. Returns an authorization URL the user must open in a browser; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional returnUrl.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

mcp_server_urlstring · uriRequired

URL of the MCP server requiring OAuth.

namestring · min: 1Required

Human-readable name to display for the connection.

custom_integration_idstring · uuidOptional

Optional ID of a custom integration this connection should be associated with.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

return_urlstringOptional

Where to send the user's browser after consent completes. Accepts an absolute URL on a domain Duvo allows, or a path relative to the Duvo frontend (e.g. /integrations/slack).

integration_typestringOptional

Optional integration type label.

Responses

200

Default Response

application/json

authorization_urlstringRequired

OAuth provider authorization URL to open in a browser

400

Default Response

application/json

401

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/oauth/mcp/start

HTTPcURLJavaScriptPython

POST /v1/connections/oauth/mcp/start HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "mcp_server_url": "https://example.com",
  "name": "text",
  "custom_integration_id": "123e4567-e89b-12d3-a456-426614174000",
  "return_url": "text",
  "integration_type": "text"
}

{
  "authorization_url": "text"
}

post

Probe an MCP server URL to discover whether it supports OAuth Dynamic Client Registration. Returns the authorization endpoint and required scopes when supported. Useful as a precursor to /v1/connections/oauth/mcp/start or /v1/connections. Performs no writes.

Authorizations

bearerAuth

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

application/json

mcp_server_urlstring · uriRequired

URL of the MCP server to probe for OAuth support.

Responses

200

Default Response

application/json

supports_dcrbooleanRequired

True if the MCP server advertises OAuth Dynamic Client Registration

authorization_endpointstringOptional

OAuth authorization endpoint advertised by the MCP server, when discoverable

scopesstring[]Optional

Scopes the MCP server requests during authorization

400

Default Response

application/json

401

Default Response

application/json

500

Default Response

application/json

post

/v1/connections/oauth/mcp/check

HTTPcURLJavaScriptPython

POST /v1/connections/oauth/mcp/check HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "mcp_server_url": "https://example.com"
}

{
  "supports_dcr": true,
  "authorization_endpoint": "text",
  "scopes": [
    "text"
  ]
}