### Complete Example: Upload Files and Start a Run

Source: https://docs.duvo.ai/user-guide/running-assignments/running-assignments-via-api

This bash script demonstrates a full workflow: creating a sandbox, uploading a file, starting a run, polling for completion, and retrieving messages. Ensure you have `jq` installed for JSON parsing.

```bash
#!/bin/bash
API_KEY="dv_your_api_key"
TEAM_ID="your-team-id"
AGENT_ID="7c9e6679-7425-40de-944b-e07fc1f90ae7"
BASE_URL="https://api.duvo.ai/v2"

# 1. Create a sandbox
SANDBOX_RESPONSE=$(curl -s -X POST "$BASE_URL/sandboxes" \
  -H "Authorization: Bearer $API_KEY")
SANDBOX_ID=$(echo $SANDBOX_RESPONSE | jq -r '.sandbox_id')
echo "Created sandbox: $SANDBOX_ID"

# 2. Upload a file
curl -X POST "$BASE_URL/sandboxes/$SANDBOX_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./input-data.csv" \
  -F "path=/workspace/input-data.csv"

# 3. Start a run with the sandbox
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\",
    \"sandbox_id\": \"$SANDBOX_ID\"
  }")
RUN_ID=$(echo $RUN_RESPONSE | jq -r '.run.id')
echo "Started run: $RUN_ID"

# 4. Poll for completion
while true; do
  STATUS_RESPONSE=$(curl -s -X GET "$BASE_URL/runs/$RUN_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.run.status')
  echo "Run status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "stopped" ]; then
    break
  fi

  sleep 5
done

echo "Run finished with status: $STATUS"

# 5. Get the conversation messages
curl -s -X GET "$BASE_URL/runs/$RUN_ID/messages?limit=50" \
  -H "Authorization: Bearer $API_KEY" | jq '.messages'
```

--------------------------------

### Duvo AI CLI Quick Start

Source: https://docs.duvo.ai/cli/index

A quick guide to installing, signing in, listing assignments, starting a job, and checking job status using the Duvo AI CLI.

```bash
# 1. Install
npm install -g @duvoai/cli

# 2. Sign in (opens your browser)
duvo login

# 3. List your Assignments
duvo agents list

# 4. Start a Job
duvo runs start --agent <agent-id>

# 5. Check Job status
duvo runs get <run-id>
```

--------------------------------

### Get a Setup by ID

Source: https://docs.duvo.ai/api-reference

Retrieve details of a specific setup using its build ID.

```http
GET /agents/{agent_id}/revisions/{build_id}
```

--------------------------------

### Push Files to Duvo and Start Job (curl)

Source: https://docs.duvo.ai/user-guide/assignment-features/file-drop-triggers

This example demonstrates the multi-step process of creating a sandbox, uploading a file, and initiating a job using curl commands.

```bash
API_KEY="dv_your_api_key"
TEAM_ID="your-team-id"
ASSIGNMENT_ID="your-assignment-id"
BASE_URL="https://api.duvo.ai/v2"

# Step 1 — Create a sandbox
SANDBOX_ID=$(curl -s -X POST "$BASE_URL/sandboxes" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.sandbox_id')

# Step 2 — Upload the file
curl -X POST "$BASE_URL/sandboxes/$SANDBOX_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./invoice.pdf" \
  -F "path=/workspace/invoice.pdf"

# Step 3 — Start the Job
curl -X POST "$BASE_URL/teams/$TEAM_ID/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$ASSIGNMENT_ID\", \"sandbox_id\": \"$SANDBOX_ID\"}"
```

--------------------------------

### Create Assignment, Build, and Start Job Example

Source: https://docs.duvo.ai/user-guide/running-assignments/creating-assignments-via-api

This bash script demonstrates creating an Assignment with its initial Build and then starting a Job on it using Duvo AI's API. It uses `curl` for API requests and `jq` for JSON parsing.

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

# 1. Create an Assignment with its first Build
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')
BUILD_ID=$(echo $AGENT_RESPONSE | jq -r '.build.id')
echo "Created Assignment: $AGENT_ID with Build: $BUILD_ID"

```

--------------------------------

### Get a Setup by ID

Source: https://docs.duvo.ai/api-reference

Retrieves a specific setup using its unique build ID.

```APIDOC
## GET /agents/{agent_id}/revisions/{build_id}

### Description
Get a Setup by ID

### Method
GET

### Endpoint
/agents/{agent_id}/revisions/{build_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the assignment.
- **build_id** (string) - Required - The ID of the setup to retrieve.
```

--------------------------------

### Promote a Setup to live

Source: https://docs.duvo.ai/api-reference

Promotes a specific setup to a live environment.

```APIDOC
## POST /revisions/{build_id}/promote

### Description
Promote a Setup to live

### Method
POST

### Endpoint
/revisions/{build_id}/promote

### Parameters
#### Path Parameters
- **build_id** (string) - Required - The ID of the setup to promote.
```

--------------------------------

### Quick Start CLI Commands

Source: https://docs.duvo.ai/cli/clarity

Basic commands to quickly search for processes, get an overview, check versions, compare, review gaps, evidence, and export process context.

```bash
duvo clarity search "invoice" --limit 5
duvo clarity overview <process-id>
duvo clarity versions <process-id>
duvo clarity compare <process-id>
duvo clarity gaps <process-id>
duvo clarity evidence <process-id>
duvo clarity export <process-id> > clarity-brief.md
```

--------------------------------

### Create a New Setup

Source: https://docs.duvo.ai/api-reference

Create a new setup (revision) for an assignment.

```http
POST /agents/{agent_id}/revisions
```

--------------------------------

### Promote a Setup to Live

Source: https://docs.duvo.ai/api-reference

Promote a specific setup (revision) to the live environment.

```http
POST /revisions/{build_id}/promote
```

--------------------------------

### Create a new Setup

Source: https://docs.duvo.ai/api-reference

Creates a new setup for a given assignment.

```APIDOC
## POST /agents/{agent_id}/revisions

### Description
Create a new Setup

### Method
POST

### Endpoint
/agents/{agent_id}/revisions

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the assignment to create the setup for.

### Request Body
(Details not provided in source)
```

--------------------------------

### Get Revision Case Queue Setup

Source: https://docs.duvo.ai/api-reference/revision-integrations/get-revision-case-queue-setup

Retrieves the setup status for case-queue integration slots for a given agent revision. It indicates the number of linked queues per slot and whether the team owns any queues, helping to identify and resolve potential runtime issues by ensuring queues are properly linked.

```APIDOC
## GET /v2/agents/{agent_id}/revisions/{build_id}/case-queue-validation

### Description
Check that this build's case-queue integration slots are wired up correctly. Returns, per case-queue-producer/consumer slot, how many queues are linked, plus whether your team owns any case queues. A slot with linked_queue_count of 0 is attached but points at no queue and will fail at runtime — link a queue with replaceRevisionIntegrationQueues before starting work.

### Method
GET

### Endpoint
/v2/agents/{agent_id}/revisions/{build_id}/case-queue-validation

### Parameters
#### Path Parameters
- **agent_id** (string (uuid)) - Required - Agent ID
- **build_id** (string (uuid)) - Required - Build ID

### Response
#### Success Response (200)
- **configs** (array) - 
  - **config_id** (string (uuid)) - Integration slot (agent_integration_config) ID
  - **integration_type** (string) - Slug of the integration type (e.g. case-queue-producer)
  - **linked_queue_count** (number) - Number of case queues currently linked to this slot

#### Response Example
{
  "configs": [
    {
      "config_id": "123e4567-e89b-12d3-a456-426614174000",
      "integration_type": "case-queue-producer",
      "linked_queue_count": 5
    }
  ]
}
```

--------------------------------

### List and Install Skills

Source: https://docs.duvo.ai/cli/managing-files-and-skills

Browse and install Skills available to your team or system-wide.

```bash
duvo skills list                                # list Skills available to your team
duvo skills list --system                       # restrict the list to system Skills
duvo skills system                              # list global system Skills available to all teams
duvo skills install <skill-id>                  # copy a system (or any accessible) Skill into your team's library
duvo skills assignments <skill-id>              # list Assignments whose live Setup references a Skill
```

--------------------------------

### Get Revision Case Queue Setup

Source: https://docs.duvo.ai/api-reference/revision-integrations/get-revision-case-queue-setup

Fetches the per-slot case-queue link summary for the build, indicating if the current team has available queues.

```APIDOC
## GET /websites/duvo_ai/revision-integrations/get-revision-case-queue-setup

### Description
Retrieves the setup configuration for revision case queues, including linked queue summaries and queue availability.

### Method
GET

### Endpoint
/websites/duvo_ai/revision-integrations/get-revision-case-queue-setup

### Parameters
#### Query Parameters
- **config_id** (string) - Required - The unique identifier for the configuration.
- **integration_type** (string) - Required - The type of integration.
- **linked_queue_count** (integer) - Required - The number of queues linked.

### Response
#### Success Response (200)
- **configs** (object) - Per-slot case-queue link summary for the build.
  - **has_available_queues** (boolean) - True if the current team owns at least one case queue.

#### Response Example
```json
{
  "configs": {
    "has_available_queues": true
  }
}
```

### Error Handling
- **400**: Bad Request - Returned when the request is malformed or invalid.
- **401**: Unauthorized - Returned when the API key is missing or invalid.
- **403**: Forbidden - Returned when the user does not have permission to access the resource.
- **404**: Not Found - Returned when the requested resource does not exist.
- **500**: Internal Server Error - Returned when an unexpected error occurs on the server.
```

--------------------------------

### Start, Get, List Messages, and Stop Jobs

Source: https://docs.duvo.ai/cli/running-jobs

Basic commands to manage the lifecycle of a Job. Add `--json` for machine-readable output.

```bash
duvo runs start --agent <agent-id>             # start a Job
duvo runs get <run-id>                         # get Job status
duvo runs messages <run-id>                    # list conversation messages
duvo runs stop <run-id>                        # stop a running Job
```

--------------------------------

### Install Duvo CLI and Agent Skills

Source: https://docs.duvo.ai/cli/index

Download the Duvo agent skills and install the Duvo CLI. Ensure you have Node.js 24+ installed. Log in to your Duvo account afterwards.

```bash
npx skills add duvoai/skills       # download the Duvo agent skills
npm install -g @duvoai/cli         # install the CLI itself (Node.js 24+)
duvo login                         # sign in
duvo whoami                        # confirm you're connected
```

--------------------------------

### Complete SKILL.md Example

Source: https://docs.duvo.ai/user-guide/skills/creating-custom-skills

A full example of a SKILL.md file, including frontmatter and Markdown content for refund processing guidelines.

```markdown
---
name: refund-processing
description: Guidelines for processing customer refund requests. Use when handling refund emails, evaluating refund eligibility, or drafting refund responses.
---

# Refund Processing Guidelines

## Overview

This skill provides guidance for handling customer refund requests according to company policy.

## Eligibility Criteria

- Request must be within 30 days of purchase
- Product must be unused or defective
- Original receipt or order number required

## Processing Steps

1. Verify the purchase in the order system
2. Check if the request meets eligibility criteria
3. If eligible, process the refund
4. If not eligible, draft a polite explanation

## Response Templates

### Approved Refund

"Thank you for contacting us. We've processed your refund of [amount]..."

### Denied Refund

"Thank you for your request. Unfortunately..."
```

--------------------------------

### Setups Tools

Source: https://docs.duvo.ai/mcp/available-tools

Tools for managing Setups, which are versioned configurations of an Assignment.

```APIDOC
## Setups

### Tools
- `listAgentRevisions`: List Setups for an Assignment.
- `getRevision`: Get a Setup by ID.
- `createRevision`: Create a new Setup for an existing Assignment.
- `updateRevision`: Update a Setup's name or SOP.
- `promoteRevision`: Promote a Setup to active, making it the one used for new Jobs.
```

--------------------------------

### Attach a Login to a Setup

Source: https://docs.duvo.ai/api-reference

Attaches a new Login to a specified Setup revision.

```APIDOC
## POST /agents/{agentId}/revisions/{buildId}/logins

### Description
Attach a Login to a Setup

### Method
POST

### Endpoint
/agents/{agentId}/revisions/{buildId}/logins
```

--------------------------------

### List built-in plugins that can be referenced in a Setup

Source: https://docs.duvo.ai/api-reference

Retrieves a list of all available built-in plugins that can be referenced when configuring a Setup.

```APIDOC
## GET /plugins/catalog

### Description
List built-in plugins that can be referenced in a Setup

### Method
GET

### Endpoint
/plugins/catalog
```

--------------------------------

### Update a Setup

Source: https://docs.duvo.ai/api-reference

Modify an existing setup using its build ID.

```http
PATCH /revisions/{build_id}
```

--------------------------------

### Attach one or more Connections to a Setup

Source: https://docs.duvo.ai/api-reference

Attaches one or more new Connections to a specified Setup revision.

```APIDOC
## POST /agents/{agent_id}/revisions/{build_id}/integrations

### Description
Attach one or more Connections to a Setup

### Method
POST

### Endpoint
/agents/{agent_id}/revisions/{build_id}/integrations
```

--------------------------------

### List Setups for an Assignment

Source: https://docs.duvo.ai/api-reference

Retrieve a list of all setups (revisions) associated with a specific assignment.

```http
GET /agents/{agent_id}/revisions
```

--------------------------------

### List Connections attached to a Setup

Source: https://docs.duvo.ai/api-reference

Retrieves a list of all Connections that are currently attached to a specific Setup revision.

```APIDOC
## GET /agents/{agent_id}/revisions/{build_id}/integrations

### Description
List Connections attached to a Setup

### Method
GET

### Endpoint
/agents/{agent_id}/revisions/{build_id}/integrations
```

--------------------------------

### Get Revision Case Queue Setup

Source: https://docs.duvo.ai/api-reference/revision-integrations/get-revision-case-queue-setup

Checks if the case-queue integration slots for a given revision are correctly configured. It returns the number of linked queues for each slot and indicates if your team owns any case queues. Ensure that slots with a linked_queue_count of 0 are updated with a queue using `replaceRevisionIntegrationQueues` before starting work.

```yaml
openapi: 3.0.3
info:
  title: Duvo Public 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
security: []
tags:
  - name: Runs
    description: Start, monitor, and manage agent runs (Jobs in the Duvo UI)
  - name: Sandboxes
    description: Create sandboxes and upload files for agent runs
  - name: Case Queues
    description: Manage case queues and their agent bindings
  - name: Cases
    description: Create, list, and manage cases and their labels within queues
  - name: Case Approvals
    description: Submit decisions on pending case approval requests issued by an agent run
  - name: Agents
    description: >-
      Create and manage agents (Assignments in the Duvo UI) for automation
      workloads
  - name: Revisions
    description: Create and manage agent revisions — the underlying Setup for an Assignment
  - name: Agent Folders
    description: Organize agents (Assignments in the Duvo UI) into folders
  - name: Agent Memory
    description: Read an agent's memory files (the Memory feature in the Duvo UI)
  - name: Schedules
    description: List schedules configured for an agent (Assignment in the Duvo UI)
  - name: Case Triggers
    description: >-
      Configure case triggers that automatically dispatch agent runs (Jobs in
      the Duvo UI) for cases added to a queue
  - name: Triggers
    description: >-
      Configure event triggers that start a Job automatically when an external
      event fires (e.g. an email arrives, a Linear issue is created, or a file
      changes in Google Drive)
  - name: Skills
    description: Manage team and system skills (reusable knowledge packs).
  - name: Files
    description: Manage team files.
  - name: Plugins
    description: Discover plugins that can be referenced from a revision.
  - name: Team
    description: Inspect the team and members associated with the API key
  - name: Integrations
    description: Browse the team's catalog of available integration types
  - name: Connections
    description: Manage your connected integrations
  - name: Credentials
    description: >-
      Manage browser logins (domain + username + password + TOTP) used by the
      browsing agent to log into websites, and attach them to assignment
      revisions
  - name: Secrets
    description: >-
      Manage env-var secrets injected into jobs, and attach them to assignment
      revisions. Only metadata is exposed; values are never returned
  - name: Revision Integrations
    description: >-
      Attach integrations to assignment revisions, pin specific connections, and
      link case queues
  - name: ClarityV2
    description: >-
      Manage Clarity v2 process snapshots, transformation proposals, and the
      extra-capture-request follow-up loop
paths:
  /v2/agents/{agent_id}/revisions/{build_id}/case-queue-validation:
    get:
      tags:
        - Revision Integrations
      summary: Get Revision Case Queue Setup
      description: >-
        Check that this build's case-queue integration slots are wired up
        correctly. Returns, per case-queue-producer/consumer slot, how many
        queues are linked, plus whether your team owns any case queues. A slot
        with linked_queue_count of 0 is attached but points at no queue and will
        fail at runtime — link a queue with replaceRevisionIntegrationQueues
        before starting work.
      operationId: getRevisionCaseQueueSetup
      parameters:
        - schema:
            type: string
            format: uuid
          in: path
          name: agent_id
          required: true
          description: Agent ID
        - schema:
            type: string
            format: uuid
          in: path
          name: build_id
          required: true
          description: Build ID
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  configs:
                    type: array
                    items:
                      type: object
                      properties:
                        config_id:
                          type: string
                          format: uuid
                          description: Integration slot (agent_integration_config) ID
                        integration_type:
                          type: string
                          description: >-
                            Slug of the integration type (e.g.
                            case-queue-producer)
                        linked_queue_count:
                          type: number
                          description: Number of case queues currently linked to this slot

```

--------------------------------

### Manage Assignment Revisions

Source: https://docs.duvo.ai/cli/managing-assignments

Manage Revisions, which are versioned Setup snapshots of Assignments. Use these commands to list, get, create, or update Revisions.

```bash
duvo revisions list --agent <agent-id>                  # list all Revisions
duvo revisions get <revision-id> --agent <agent-id>     # get a specific Revision
duvo revisions create \
  --agent <agent-id> \
  --name "v2" \
  --config-file path/to/config.json                     # use `-` to read Setup from stdin
duvo revisions update <revision-id> \
  --config-file path/to/config.json                     # update an existing Revision's Setup
```

--------------------------------

### List Available Plugins

Source: https://docs.duvo.ai/cli/managing-files-and-skills

Browse all plugins that can be referenced in an Assignment's Setup.

```bash
duvo plugins list                               # browse every plugin you can reference in a Setup
duvo plugins list --json
```

--------------------------------

### Start Composio Connection

Source: https://docs.duvo.ai/user-guide/running-assignments/creating-assignments-via-api

Initiates a Composio-backed connection. For OAuth tools, returns a redirect URL for user consent. For non-OAuth tools, it may finalize synchronously.

```bash
# POST /teams/{teamId}/connections/composio/start
```

--------------------------------

### Start Composio Connection

Source: https://docs.duvo.ai/api-reference/connections/start-composio-connection

Initiates a Composio-backed connection. This endpoint is used to start the process of connecting with Composio, which may involve an OAuth handshake or direct authentication depending on the scheme. A `redirect_url` is returned for OAuth flows, guiding the user through the consent process. For non-OAuth schemes, the connection might finalize synchronously.

```APIDOC
## POST /v2/teams/{teamId}/connections/composio/start

### Description
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 `/v2/teams/:team_id/connections/composio/finalize` to provision the corresponding Duvo connection.

### Method
POST

### Endpoint
/v2/teams/{teamId}/connections/composio/start

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team.

#### Request Body
- **auth_config_id** (string) - Required - Composio auth-config ID for the toolkit. Obtain it from Composio's auth-config catalog or by listing existing configs.
- **callback_url** (string) - Optional - Where to send the user's browser after they finish the Composio consent screen. Must be an absolute URL.
- **auth_scheme** (string) - Optional - Composio auth scheme (e.g. 'OAUTH2', 'API_KEY', 'BEARER_TOKEN'). Required when supplying non-OAuth credentials in `auth_fields`.
- **auth_fields** (object) - Optional - Auth field values keyed by field name. For OAuth, these are passed in `connection.data`; for API_KEY/BEARER_TOKEN/etc.,

### Request Example
```json
{
  "auth_config_id": "comp_abc123",
  "callback_url": "https://your-app.com/callback",
  "auth_scheme": "OAUTH2",
  "auth_fields": {
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }
}
```

### Response
#### Success Response (200)
- **redirect_url** (string) - The URL the user must visit to complete the OAuth handshake, or null if the connection finalizes synchronously.

#### Response Example
```json
{
  "redirect_url": "https://composio.com/oauth/authorize?client_id=..."
}
```
```

--------------------------------

### Start a Duvo Job and Wait for Completion

Source: https://docs.duvo.ai/cli/scripting-and-ci

Initiate a Duvo run and then poll its status using `duvo runs get` until it reaches a terminal state (completed, failed, or stopped).

```bash
RUN_ID=$(duvo runs start \
  --agent "$AGENT_ID" \
  --message "Process the daily batch." \
  --json | jq -r '.run.id')

while true; do
  STATUS=$(duvo runs get "$RUN_ID" --json | jq -r '.run.id')
  case "$STATUS" in
    completed|failed|stopped) break ;; 
  esac
  sleep 10
done

if [ "$STATUS" != "completed" ]; then
  echo "Job failed with status: $STATUS" >&2
  exit 1
fi
echo "Job $RUN_ID completed."
```

--------------------------------

### Get Revision Case Queue Setup

Source: https://docs.duvo.ai/llms.txt

Checks if the case-queue integration slots for the current build are correctly configured. It returns the number of linked queues for each case-producer/consumer slot and indicates if your team owns any case queues. A slot with a linked_queue_count of 0 is attached but not linked to any queue and will cause runtime errors.

```APIDOC
## GET /v2/revision-integrations/case-queue-setup

### Description
Check that this build's case-queue integration slots are wired up correctly. Returns, per case-queue-producer/consumer slot, how many queues are linked, plus whether your team owns any case queues. A slot with linked_queue_count of 0 is attached but points at no queue and will fail at runtime — link…

### Method
GET

### Endpoint
/v2/revision-integrations/case-queue-setup

### Response
#### Success Response (200)
- **linked_queue_count** (integer) - The number of queues linked to the slot.
- **owns_case_queues** (boolean) - Whether your team owns any case queues.
```

--------------------------------

### Finalize Composio Connection

Source: https://docs.duvo.ai/user-guide/running-assignments/creating-assignments-via-api

Completes a Composio connection after the start step, especially after an OAuth flow or synchronous non-OAuth start. Requires the `connected_account_id` from the start step.

```bash
# POST /teams/{teamId}/connections/composio/finalize
```

--------------------------------

### Effective Skill Guidance Example

Source: https://docs.duvo.ai/user-guide/skills/creating-custom-skills

Illustrates how to provide specific, actionable instructions in a skill instead of vague statements. This format helps users understand exactly what to do.

```markdown
When handling customer complaints:
1. Acknowledge their frustration
2. Apologize for the inconvenience
3. Ask clarifying questions to understand the issue
4. Propose a specific solution
5. Follow up within 24 hours
```

--------------------------------

### Start a Run with Optional Parameters

Source: https://docs.duvo.ai/api-reference/runs/start-run

Start a new agent run with additional options such as an initial message, a sandbox ID, or a webhook URL for event notifications.

```shell
curl -X POST \
  https://api.duvo.ai/v2/teams/YOUR_TEAM_ID/runs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "message": "Please analyze this document.",
    "sandbox_id": "YOUR_SANDBOX_ID",
    "webhook_url": "https://example.com/webhook"
  }'
```

--------------------------------

### Update a Setup

Source: https://docs.duvo.ai/api-reference

Updates an existing setup identified by its build ID.

```APIDOC
## PATCH /revisions/{build_id}

### Description
Update a Setup

### Method
PATCH

### Endpoint
/revisions/{build_id}

### Parameters
#### Path Parameters
- **build_id** (string) - Required - The ID of the setup to update.

### Request Body
(Details not provided in source)
```

--------------------------------

### Example Skill Folder Structure

Source: https://docs.duvo.ai/user-guide/skills/creating-custom-skills

Illustrates the typical folder structure for a multi-file custom skill, including the main `SKILL.md` and supporting reference files.

```text
brand-voice/
├── SKILL.md
├── TONE-GUIDE.md
└── examples/
    ├── email-examples.md
    └── social-examples.md
```

--------------------------------

### Upload Files to a Sandbox Before Starting a Job

Source: https://docs.duvo.ai/cli/scripting-and-ci

Create a sandbox, upload necessary files to it, and then start a Duvo run using the sandbox ID. Handles files smaller than 10MB.

```bash
SANDBOX_ID=$(duvo sandboxes create --json | jq -r '.sandbox.id')

duvo sandboxes upload "$SANDBOX_ID" ./input-data.csv

RUN_ID=$(duvo runs start \
  --agent "$AGENT_ID" \
  --sandbox-id "$SANDBOX_ID" \
  --json | jq -r '.run.id')
```

--------------------------------

### Remove a Secret from a Setup

Source: https://docs.duvo.ai/api-reference

Removes a specific Secret that is attached to a Setup revision.

```APIDOC
## DELETE /agents/{agentId}/revisions/{buildId}/credentials/{credentialId}

### Description
Remove a Secret from a Setup

### Method
DELETE

### Endpoint
/agents/{agentId}/revisions/{buildId}/credentials/{credentialId}
```

--------------------------------

### List Connection instances for a Connection slot

Source: https://docs.duvo.ai/api-reference

Lists all available Connection instances that can be used for a specific Connection slot within a Setup revision.

```APIDOC
## GET /agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/connections

### Description
List Connection instances for a Connection slot

### Method
GET

### Endpoint
/agents/{agent_id}/revisions/{build_id}/integrations/{integration_id}/connections
```