Creating Assignments via API

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 point in 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

get

List agents for your team.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Query parameters

limitinteger · min: 1 · max: 100Optional

Number of agents per page (1-100, default 20)

Default: 20

offsetintegerOptional

Number of agents to skip

Default: 0

Responses

200

Default Response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

401

Default Response

application/json

500

Default Response

application/json

get

/v1/agents

HTTPcURLJavaScriptPython

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

{
  "agents": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

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.

post

Create a new agent. Optionally include a build configuration to create the first build in the same request.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Body

application/json

namestring · min: 1Required

Human-readable agent name

Responses

201

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

500

Default Response

application/json

post

/v1/agents

HTTPcURLJavaScriptPython

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

{
  "name": "text",
  "build": {
    "name": "text",
    "config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

{
  "agent": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "created_at": "text",
    "updated_at": "text"
  },
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "config": {
      "version": "v1",
      "data": {
        "model": "text",
        "temperature": 1,
        "max_output_tokens": 1,
        "top_p": 1,
        "store": true,
        "tools": [
          {
            "type": "mcp",
            "server_label": "text",
            "server_url": "text",
            "allowed_tools": [
              "text"
            ],
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "require_approval": "always"
          }
        ],
        "input": "text",
        "text": {
          "format": {
            "type": "text"
          }
        },
        "files": [
          "text"
        ],
        "skills": [
          "text"
        ]
      }
    },
    "revision_number": 1,
    "created_at": "text",
    "updated_at": "text"
  }
}

Get an Assignment

get

Get an agent by ID.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Path parameters

agent_idstring · uuidRequired

Responses

200

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/agents/{agent_id}

HTTPcURLJavaScriptPython

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

{
  "agent": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "created_at": "text",
    "updated_at": "text"
  },
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "config": {
      "version": "v1",
      "data": {
        "model": "text",
        "temperature": 1,
        "max_output_tokens": 1,
        "top_p": 1,
        "store": true,
        "tools": [
          {
            "type": "mcp",
            "server_label": "text",
            "server_url": "text",
            "allowed_tools": [
              "text"
            ],
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "require_approval": "always"
          }
        ],
        "input": "text",
        "text": {
          "format": {
            "type": "text"
          }
        },
        "files": [
          "text"
        ],
        "skills": [
          "text"
        ]
      }
    },
    "revision_number": 1,
    "created_at": "text",
    "updated_at": "text"
  }
}

---

Builds

Get a Build

get

Get a build by ID.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Path parameters

build_idstring · uuidRequired

Responses

200

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/builds/{build_id}

HTTPcURLJavaScriptPython

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

{
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "config": {
      "version": "v1",
      "data": {
        "model": "text",
        "temperature": 1,
        "max_output_tokens": 1,
        "top_p": 1,
        "store": true,
        "tools": [
          {
            "type": "mcp",
            "server_label": "text",
            "server_url": "text",
            "allowed_tools": [
              "text"
            ],
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "require_approval": "always"
          }
        ],
        "input": "text",
        "text": {
          "format": {
            "type": "text"
          }
        },
        "files": [
          "text"
        ],
        "skills": [
          "text"
        ]
      }
    },
    "revision_number": 1,
    "created_at": "text",
    "updated_at": "text"
  }
}

List Builds for an Assignment

get

List builds for an agent.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Path parameters

agent_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Number of builds per page (1-100, default 20)

Default: 20

offsetintegerOptional

Number of builds to skip

Default: 0

Responses

200

Default Response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Default Response

application/json

401

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/agents/{agent_id}/builds

HTTPcURLJavaScriptPython

GET /v1/agents/{agent_id}/builds HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "builds": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "config": {
        "version": "v1",
        "data": {
          "model": "text",
          "temperature": 1,
          "max_output_tokens": 1,
          "top_p": 1,
          "store": true,
          "tools": [
            {
              "type": "mcp",
              "server_label": "text",
              "server_url": "text",
              "allowed_tools": [
                "text"
              ],
              "headers": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "require_approval": "always"
            }
          ],
          "input": "text",
          "text": {
            "format": {
              "type": "text"
            }
          },
          "files": [
            "text"
          ],
          "skills": [
            "text"
          ]
        }
      },
      "revision_number": 1,
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

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.

post

Create a new build for an existing agent.

Authorizations

bearerAuth

AuthorizationstringRequired

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

Body

application/json

agent_idstring · uuidRequired

Agent ID

namestring · min: 1Required

Build name

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/builds

HTTPcURLJavaScriptPython

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

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "build": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "config": {
      "version": "v1",
      "data": {
        "model": "text",
        "temperature": 1,
        "max_output_tokens": 1,
        "top_p": 1,
        "store": true,
        "tools": [
          {
            "type": "mcp",
            "server_label": "text",
            "server_url": "text",
            "allowed_tools": [
              "text"
            ],
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "require_approval": "always"
          }
        ],
        "input": "text",
        "text": {
          "format": {
            "type": "text"
          }
        },
        "files": [
          "text"
        ],
        "skills": [
          "text"
        ]
      }
    },
    "revision_number": 1,
    "created_at": "text",
    "updated_at": "text"
  },
  "agent": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

---

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.