Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Duvo Public API lets you create and manage Assignments and Builds 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 Assignments via API.

​
Key Concepts

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

​
Endpoints

​
Assignments

​
List Assignments

API: GET /v1/agents — see the API Reference for full details.

​
Create an Assignment

Creates a new Assignment. You can optionally include a build object in the request body to create the first Build in the same call, saving you a separate request.
API: POST /v1/agents — see the API Reference for full details.

​
Get an Assignment

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

​
Update an Assignment

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

​
Builds

​
Get a Build

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

​
List Builds for an Assignment

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

​
Create a Build

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

​
Update a Build

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

​
Folders

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

​
List Folders

API: GET /v1/agent-folders — see the API Reference for full details.

​
Create a Folder

API: POST /v1/agent-folders — see the API Reference for full details.

​
Update a Folder

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

​
Delete a Folder

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

​
Move Assignments into a Folder

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

​
Connections

Connections represent OAuth accounts or credentials that your assignments 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 /v1/connections — see the API Reference for full details.

​
Get a Connection

API: GET /v1/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 /v1/connections/{connection_id}/credentials — see the API Reference for full details.

​
Create a Connection

Creates a user-provided connection (custom MCP server with a URL and optional credential headers). For OAuth-based connections (native providers, Composio, or OAuth MCP servers), use the dedicated OAuth endpoints below instead.
API: POST /v1/connections — see the API Reference for full details.

​
Update a Connection

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

​
Delete a Connection

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

​
Start Native OAuth Connection

Starts an OAuth flow for a native provider (Gmail, Google Sheets, Google Drive, Google Calendar, Google Docs, Microsoft Outlook, Microsoft Excel, Microsoft Word, Microsoft Teams, Microsoft SharePoint, Microsoft OneDrive). 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.
API: POST /v1/connections/oauth/native/{provider}/start — see the API Reference for full details.

​
Start MCP OAuth Connection

Starts an OAuth flow for a custom MCP server that supports Dynamic Client Registration (RFC 7591). Returns an authorization URL the user must open in a browser. Once they grant consent, Duvo creates the connection. Use Check MCP OAuth Support first to confirm the server supports this flow.
API: POST /v1/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 /v1/connections/oauth/mcp/check — see the API Reference for full details.

​
Probe MCP Server

Tests an MCP server URL and returns the list of tools it exposes. Verifies the server is reachable and that any authentication headers are accepted. Performs no writes. Use this to validate a custom MCP server before creating a connection.
API: POST /v1/connections/mcp/probe — see the API Reference for full details.

​
Start Composio Connection

Starts a Composio-backed connection. For OAuth-based toolkits (Slack, HubSpot, Zendesk, Asana, etc.), returns a redirect_url you open in the user’s browser to complete the consent flow. For non-OAuth toolkits (API key, Bearer token), the connection may finalize synchronously with redirect_url: null. After the flow completes, call Finalize Composio Connection to provision the connection in Duvo.
API: POST /v1/connections/composio/start — see the API Reference for full details.

​
Finalize Composio Connection

Completes a Composio connection after the start step. Call this once the user has finished the OAuth flow (or immediately after a synchronous non-OAuth start). Pass the connected_account_id returned by Start Composio Connection.
API: POST /v1/connections/composio/finalize — see the API Reference for full details.

​
Schedules

​
List Schedules for an Assignment

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

​
Complete Example

This example creates an Assignment with its first Build in a single request, then starts a Job on it. 
#!/bin/bash
API_KEY="dv_your_api_key"
BASE_URL="https://api.duvo.ai/v1"

# 1. Create an Assignment with its first Build
AGENT_RESPONSE=$(curl -s -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Processor",
    "build": {
      "name": "v1",
      "config": {
        "version": "v2",
        "data": {
          "models": {
            "agent": { "model": "claude-sonnet-4-20250514" },
            "browsing": { "provider": "browserbase", "model": "gpt-4o" }
          },
          "input": "Process invoices from the uploaded files and extract line items.",
          "files": [],
          "skills": []
        }
      }
    }
  }')

AGENT_ID=$(echo $AGENT_RESPONSE | jq -r '.agent.id')
BUILD_ID=$(echo $AGENT_RESPONSE | jq -r '.build.id')
echo "Created Assignment: $AGENT_ID with Build: $BUILD_ID"

# 2. Start a Job on the new Assignment
RUN_RESPONSE=$(curl -s -X POST "$BASE_URL/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT_ID\"}")

RUN_ID=$(echo $RUN_RESPONSE | jq -r '.run.id')
echo "Started Job: $RUN_ID"
For more details on starting and monitoring Jobs, see Running Assignments via API.