# 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](https://docs.duvo.ai/running-assignments/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 /v1/agents

> List agents for your team.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents":{"get":{"tags":["Agents"],"description":"List agents for your team.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of agents per page (1-100, default 20)"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of agents to skip"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["agents","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}}}}}}}}}
```

#### 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 /v1/agents

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

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents":{"post":{"tags":["Agents"],"description":"Create a new agent. Optionally include a build configuration to create the first build in the same request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Human-readable agent name"},"build":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Build name"},"config":{"type":"object","additionalProperties":{},"description":"Build configuration"}},"required":["name","config"],"additionalProperties":false,"description":"Optional initial build configuration. When provided, a build is created alongside the agent."}},"required":["name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false},"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"required":["agent"],"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}}}}}}}}}
```

#### Get an Assignment

## GET /v1/agents/{agent\_id}

> Get an agent by ID.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents/{agent_id}":{"get":{"tags":["Agents"],"description":"Get an agent by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"agent_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false},"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"required":["agent"],"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}}}},"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}}}}}}}}}
```

***

### Builds

#### Get a Build

## GET /v1/builds/{build\_id}

> Get a build by ID.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Builds","description":"Create and manage agent builds/configurations"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/builds/{build_id}":{"get":{"tags":["Builds"],"description":"Get a build by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"build_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"required":["build"],"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}}}},"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}}}}}}}}}
```

#### List Builds for an Assignment

## GET /v1/agents/{agent\_id}/builds

> List builds for an agent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Builds","description":"Create and manage agent builds/configurations"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents/{agent_id}/builds":{"get":{"tags":["Builds"],"description":"List builds for an agent.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of builds per page (1-100, default 20)"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of builds to skip"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"agent_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"builds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["builds","total","limit","offset"],"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}}}},"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}}}}}}}}}
```

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

> Create a new build for an existing agent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Builds","description":"Create and manage agent builds/configurations"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/builds":{"post":{"tags":["Builds"],"description":"Create a new build for an existing agent.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"name":{"type":"string","minLength":1,"description":"Build name"},"config":{"type":"object","additionalProperties":{},"description":"Build configuration"}},"required":["agent_id","name","config"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false},"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false}},"required":["build","agent"],"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}}}},"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}}}}}}}}}
```

***

## Complete Example

This example creates an Assignment with its first Build in a single request, then starts a Job on it.

```bash
#!/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](https://docs.duvo.ai/running-assignments/running-assignments-via-api).