> ## 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.

# Creating Agents via API

> Provision and manage Agents, Revisions, folders, connections, and schedules programmatically through the Duvo Public API.

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](/user-guide/running-assignments/running-assignments-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](/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](/api-reference) for full details.

#### Get an Agent

> **API**: `GET /agents/{agent_id}` — see the [API Reference](/api-reference) for full details.

#### Update an Agent

> **API**: `PATCH /agents/{agent_id}` — see the [API Reference](/api-reference) for full details.

***

### Revisions

#### Get a Revision

> **API**: `GET /agents/{agent_id}/revisions/{build_id}` — see the [API Reference](/api-reference) for full details.

#### List Revisions for an Agent

> **API**: `GET /agents/{agent_id}/revisions` — see the [API Reference](/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](/api-reference) for full details.

#### Update a Revision

> **API**: `PATCH /revisions/{build_id}` — see the [API Reference](/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](/api-reference) for full details.

#### Create a Folder

> **API**: `POST /teams/{teamId}/agent-folders` — see the [API Reference](/api-reference) for full details.

#### Update a Folder

> **API**: `PATCH /agent-folders/{folder_id}` — see the [API Reference](/api-reference) for full details.

#### Delete a Folder

> **API**: `DELETE /agent-folders/{folder_id}` — see the [API Reference](/api-reference) for full details.

#### Move Agents into a Folder

> **API**: `POST /teams/{teamId}/agent-folders/move-agents` — see the [API Reference](/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](#start-native-oauth-connection)
* **Custom MCP with OAuth** — Use [Start MCP OAuth Connection](#start-mcp-oauth-connection)
* **User-provided credentials** (Snowflake, Tableau, custom MCP with API keys) — Use [Create a Connection](#create-a-connection)

#### 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](/api-reference) for full details.

#### Get a Connection

> **API**: `GET /connections/{connection_id}` — see the [API Reference](/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](/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 or OAuth MCP servers), use the dedicated OAuth endpoints below instead.

> **API**: `POST /teams/{teamId}/connections` — see the [API Reference](/api-reference) for full details.

#### Update a Connection

> **API**: `PATCH /connections/{connection_id}` — see the [API Reference](/api-reference) for full details.

#### Delete a Connection

> **API**: `DELETE /connections/{connection_id}` — see the [API Reference](/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](#list-connections) to detect when the new connection appears.

> **API**: `POST /teams/{teamId}/connections/oauth/native/{provider}/start` — see the [API Reference](/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](#check-mcp-oauth-support) first to confirm the server supports this flow.

> **API**: `POST /teams/{teamId}/connections/oauth/mcp/start` — see the [API Reference](/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](#start-mcp-oauth-connection).

> **API**: `POST /connections/oauth/mcp/check` — see the [API Reference](/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 /teams/{teamId}/connections/mcp/probe` — see the [API Reference](/api-reference) for full details.

***

### Schedules

#### List Schedules for an Agent

> **API**: `GET /agents/{agent_id}/schedules` — see the [API Reference](/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.

```bash theme={"dark"}
#!/bin/bash
API_KEY="dv_your_api_key"
TEAM_ID="your-team-id"
BASE_URL="https://api.duvo.ai/v2"

# 1. Create an Agent with its first Revision
AGENT_RESPONSE=$(curl -s -X POST "$BASE_URL/teams/$TEAM_ID/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')
REVISION_ID=$(echo $AGENT_RESPONSE | jq -r '.build.id')
echo "Created Agent: $AGENT_ID with Revision: $REVISION_ID"

# 2. Start a Run on the new Agent
RUN_RESPONSE=$(curl -s -X POST "$BASE_URL/teams/$TEAM_ID/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 Run: $RUN_ID"
```

For more details on starting and monitoring Runs, see [Running Agents via API](/user-guide/running-assignments/running-assignments-via-api).