OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Connections API
description: Public API for programmatic access to Duvo. Authenticate with API keys created in the Duvo dashboard.
version: 1.0.0
servers:
- url: https://api.duvo.ai
description: Production server
tags:
- name: Connections
description: Manage your connected integrations
paths:
/v2/teams/{teamId}/connections/oauth/native/{provider}/start:
post:
operationId: startNativeOAuth
tags:
- Connections
description: 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 `/v2/teams/:team_id/connections` to detect the new connection.
requestBody:
required: true
content:
application/json:
schema:
default: {}
type: object
properties:
return_url:
description: Where to send the user's browser after OAuth completes.
type: string
reconnect_instance_id:
description: When set, the OAuth flow will update the existing connection in place rather than creating a new one.
type: string
format: uuid
additionalProperties:
type: string
parameters:
- schema:
type: string
in: path
name: provider
required: true
description: OAuth provider slug (e.g. 'google', 'gmail', 'googlesheets', 'outlook'). Must match a configured native OAuth provider.
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
authorization_url:
type: string
description: OAuth provider authorization URL to open in a browser
required:
- authorization_url
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Start Native OAuth
/v2/teams/{teamId}/connections/oauth/mcp/start:
post:
operationId: authorizeMcpOAuth
tags:
- Connections
description: 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`.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mcp_server_url:
type: string
format: uri
description: URL of the MCP server requiring OAuth.
name:
type: string
minLength: 1
description: Human-readable name to display for the connection.
custom_integration_id:
description: Optional ID of a custom integration this connection should be associated with.
type: string
format: uuid
return_url:
description: 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`).
type: string
integration_type:
description: Optional integration type label.
type: string
reconnect_instance_id:
description: When set, the OAuth flow will update the existing connection in place rather than creating a new one.
type: string
format: uuid
required:
- mcp_server_url
- name
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
authorization_url:
type: string
description: OAuth provider authorization URL to open in a browser
required:
- authorization_url
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Authorize MCP OAuth
/v2/connections/oauth/mcp/check:
post:
operationId: checkMcpOAuth
tags:
- Connections
description: 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 `/v2/teams/:team_id/connections/oauth/mcp/start` or `/v2/teams/:team_id/connections`. Performs no writes.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mcp_server_url:
type: string
format: uri
description: URL of the MCP server to probe for OAuth support.
required:
- mcp_server_url
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
supports_dcr:
type: boolean
description: True if the MCP server advertises OAuth Dynamic Client Registration
authorization_endpoint:
description: OAuth authorization endpoint advertised by the MCP server, when discoverable
type: string
scopes:
description: Scopes the MCP server requests during authorization
type: array
items:
type: string
required:
- supports_dcr
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Check MCP OAuth
/v2/connections/{connection_id}:
get:
operationId: getConnection
tags:
- Connections
description: Get one of your connections by ID.
parameters:
- schema:
type: string
format: uuid
in: path
name: connection_id
required: true
description: Connection ID
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
provider:
type: string
user_id:
nullable: true
type: string
team_id:
type: string
server_url:
type: string
transport_type:
type: string
enum:
- stdio
- sse
- http
auth_method:
nullable: true
type: string
custom_integration_id:
nullable: true
type: string
icon_url:
nullable: true
type: string
oauth_provider:
nullable: true
type: string
oauth_provider_key:
nullable: true
type: string
oauth_scopes:
nullable: true
type: array
items:
type: string
has_headers:
type: boolean
has_oauth_tokens:
type: boolean
integration_id:
nullable: true
type: string
shared:
type: boolean
created_by:
nullable: true
type: string
broken_at:
nullable: true
type: string
format: date-time
broken_reason:
nullable: true
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- type
- provider
- user_id
- team_id
- created_at
- updated_at
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Get Connection
patch:
operationId: updateConnection
tags:
- Connections
description: 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.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
server_url:
type: string
format: uri
auth_method:
type: string
enum:
- url
- oauth
- apikey
- headers
headers:
nullable: true
type: object
properties:
plaintext:
type: object
additionalProperties:
type: string
secret:
type: object
additionalProperties:
type: string
shared:
type: boolean
parameters:
- schema:
type: string
format: uuid
in: path
name: connection_id
required: true
description: Connection ID
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
provider:
type: string
user_id:
nullable: true
type: string
team_id:
type: string
server_url:
type: string
transport_type:
type: string
enum:
- stdio
- sse
- http
auth_method:
nullable: true
type: string
custom_integration_id:
nullable: true
type: string
icon_url:
nullable: true
type: string
oauth_provider:
nullable: true
type: string
oauth_provider_key:
nullable: true
type: string
oauth_scopes:
nullable: true
type: array
items:
type: string
has_headers:
type: boolean
has_oauth_tokens:
type: boolean
integration_id:
nullable: true
type: string
shared:
type: boolean
created_by:
nullable: true
type: string
broken_at:
nullable: true
type: string
format: date-time
broken_reason:
nullable: true
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- type
- provider
- user_id
- team_id
- created_at
- updated_at
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Update Connection
delete:
operationId: deleteConnection
tags:
- Connections
description: Delete a connection (disconnects the user's connection and removes any triggers bound to it).
parameters:
- schema:
type: string
format: uuid
in: path
name: connection_id
required: true
description: Connection ID
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Delete Connection
/v2/connections/{connection_id}/credentials:
get:
operationId: getConnectionCredentials
tags:
- Connections
description: 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.
parameters:
- schema:
type: string
format: uuid
in: path
name: connection_id
required: true
description: Connection ID
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
headers:
type: object
additionalProperties:
type: string
required:
- id
- headers
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Get Connection Credentials
/v2/teams/{teamId}/connections:
get:
operationId: listConnections
tags:
- Connections
description: 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.
parameters:
- schema:
type: string
in: query
name: type
required: false
- schema:
default: 100
type: integer
minimum: 1
maximum: 100
in: query
name: limit
required: false
- schema:
type: integer
minimum: 0
maximum: 9007199254740991
in: query
name: offset
required: false
- schema:
type: string
in: path
name: teamId
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
integrations:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
provider:
type: string
user_id:
nullable: true
type: string
team_id:
type: string
server_url:
type: string
transport_type:
type: string
enum:
- stdio
- sse
- http
auth_method:
nullable: true
type: string
custom_integration_id:
nullable: true
type: string
icon_url:
nullable: true
type: string
oauth_provider:
nullable: true
type: string
oauth_provider_key:
nullable: true
type: string
oauth_scopes:
nullable: true
type: array
items:
type: string
has_headers:
type: boolean
has_oauth_tokens:
type: boolean
integration_id:
nullable: true
type: string
shared:
type: boolean
created_by:
nullable: true
type: string
broken_at:
nullable: true
type: string
format: date-time
broken_reason:
nullable: true
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- type
- provider
- user_id
- team_id
- created_at
- updated_at
additionalProperties: false
total:
type: integer
minimum: 0
maximum: 9007199254740991
limit:
type: integer
minimum: 1
maximum: 9007199254740991
offset:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- integrations
- total
- limit
- offset
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: List Connections
post:
operationId: createConnection
tags:
- Connections
description: Create a new user-provided connection (custom MCP server) for the current team. OAuth-based integrations (native) require an interactive browser flow — start them with the dedicated OAuth endpoints (`/v
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-connections-api-openapi.yml