# 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](/running-assignments/running-assignments-via-api.md).

***

## 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 (Assignments in the Duvo UI) 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":{"operationId":"listAgents","tags":["Agents"],"description":"List agents for your team.","parameters":[{"schema":{"default":"false","type":"string","enum":["true","false"]},"in":"query","name":"include_schedules","required":false,"description":"Include the authenticated user's schedules for each agent in the response. Schedules are per-user, so this only returns schedules the current user owns."},{"schema":{"default":20,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of agents per page (1-100, default 20)"},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"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","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"slack_enabled":{"nullable":true,"type":"boolean"},"microsoft_teams_enabled":{"nullable":true,"type":"boolean"},"agentic_memory_enabled":{"nullable":true,"type":"boolean"},"team_id":{"nullable":true,"type":"string"},"thread_id":{"nullable":true,"type":"string"},"folder_id":{"nullable":true,"type":"string"},"pinned_at":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"last_run_at":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"updated_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"latest_build":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false},"integration_configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"integration_id":{"type":"string"},"integration_type":{"type":"string"},"integration_name":{"type":"string"},"created_at":{"type":"string"},"icon_url":{"nullable":true,"type":"string"},"is_connected":{"type":"boolean"}},"required":["id","integration_id","integration_type","integration_name","created_at"],"additionalProperties":false}},"user_triggers":{"type":"object","properties":{"slack_mention":{"type":"boolean"},"slack_channel":{"type":"boolean"},"teams_mention":{"type":"boolean"}},"required":["slack_mention","slack_channel","teams_mention"],"additionalProperties":false},"case_trigger_enabled":{"type":"boolean"},"case_trigger_has_conflict":{"type":"boolean"},"case_trigger_conflicting_agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"case_queue_name":{"nullable":true,"type":"string"}},"required":["id","name","slack_enabled","microsoft_teams_enabled","agentic_memory_enabled","team_id","thread_id","created_at","updated_at","last_run_at","latest_build","integration_configs"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["agents","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}}}},"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 (Assignments in the Duvo UI) 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":{"operationId":"createAgent","tags":["Agents"],"description":"Create a new agent. Optionally include a build configuration to create the first build in the same request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Human-readable agent name"},"thread_id":{"nullable":true,"description":"Existing thread ID to associate with the agent","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"source_build_id":{"nullable":true,"description":"Build ID whose case-queue-consumer setup should be copied to the new agent","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"build":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Build name"},"config":{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"description":"Model configuration for each capability the agent uses"},"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"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"]}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"]}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"]}}},"additionalProperties":{}}},"required":["models","input"],"description":"Agent configuration payload"}},"required":["version","data"],"description":"Build configuration (latest schema version only; legacy v1 configs are not accepted)"}},"required":["name","config"],"description":"Optional inline build. When present, a first build is created alongside the agent."}},"required":["name"]}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"slack_enabled":{"nullable":true,"type":"boolean"},"microsoft_teams_enabled":{"nullable":true,"type":"boolean"},"agentic_memory_enabled":{"nullable":true,"type":"boolean"},"team_id":{"nullable":true,"type":"string"},"thread_id":{"nullable":true,"type":"string"},"folder_id":{"nullable":true,"type":"string"},"pinned_at":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"last_run_at":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"updated_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"latest_build":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false},"integration_configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"integration_id":{"type":"string"},"integration_type":{"type":"string"},"integration_name":{"type":"string"},"created_at":{"type":"string"},"icon_url":{"nullable":true,"type":"string"},"is_connected":{"type":"boolean"}},"required":["id","integration_id","integration_type","integration_name","created_at"],"additionalProperties":false}},"user_triggers":{"type":"object","properties":{"slack_mention":{"type":"boolean"},"slack_channel":{"type":"boolean"},"teams_mention":{"type":"boolean"}},"required":["slack_mention","slack_channel","teams_mention"],"additionalProperties":false},"case_trigger_enabled":{"type":"boolean"},"case_trigger_has_conflict":{"type":"boolean"},"case_trigger_conflicting_agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"case_queue_name":{"nullable":true,"type":"string"}},"required":["id","name","slack_enabled","microsoft_teams_enabled","agentic_memory_enabled","team_id","thread_id","created_at","updated_at","last_run_at","latest_build","integration_configs"],"additionalProperties":false},"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","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}}}},"403":{"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 (Assignments in the Duvo UI) 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":{"operationId":"getAgent","tags":["Agents"],"description":"Get an agent by ID.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"agent_id","required":true,"description":"The agent's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"slack_enabled":{"nullable":true,"type":"boolean"},"microsoft_teams_enabled":{"nullable":true,"type":"boolean"},"agentic_memory_enabled":{"nullable":true,"type":"boolean"},"team_id":{"nullable":true,"type":"string"},"thread_id":{"nullable":true,"type":"string"},"folder_id":{"nullable":true,"type":"string"},"pinned_at":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"last_run_at":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"updated_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"latest_build":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false},"integration_configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"integration_id":{"type":"string"},"integration_type":{"type":"string"},"integration_name":{"type":"string"},"created_at":{"type":"string"},"icon_url":{"nullable":true,"type":"string"},"is_connected":{"type":"boolean"}},"required":["id","integration_id","integration_type","integration_name","created_at"],"additionalProperties":false}},"user_triggers":{"type":"object","properties":{"slack_mention":{"type":"boolean"},"slack_channel":{"type":"boolean"},"teams_mention":{"type":"boolean"}},"required":["slack_mention","slack_channel","teams_mention"],"additionalProperties":false},"case_trigger_enabled":{"type":"boolean"},"case_trigger_has_conflict":{"type":"boolean"},"case_trigger_conflicting_agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"case_queue_name":{"nullable":true,"type":"string"}},"required":["id","name","slack_enabled","microsoft_teams_enabled","agentic_memory_enabled","team_id","thread_id","created_at","updated_at","last_run_at","latest_build","integration_configs"],"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}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Short error code"},"team_id":{"description":"ID of the team that owns the agent, so the client can auto-switch teams","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}}}}}}}}}
```

#### Update an Assignment

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

> Update an agent's display name or delivery settings.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents (Assignments in the Duvo UI) 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}":{"patch":{"operationId":"updateAgent","tags":["Agents"],"description":"Update an agent's display name or delivery settings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New agent display name."},"slack_enabled":{"type":"boolean","description":"Whether the agent is reachable via Slack."},"microsoft_teams_enabled":{"type":"boolean","description":"Whether the agent is reachable via Microsoft Teams."},"agentic_memory_enabled":{"type":"boolean","description":"Toggle agentic memory for the agent."},"thread_id":{"nullable":true,"description":"Thread id to associate with the agent, or null to clear.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"pinned":{"type":"boolean","description":"Pin the agent to the top of the team's assignment list (true) or unpin it (false)."}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"agent_id","required":true,"description":"The agent's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"slack_enabled":{"nullable":true,"type":"boolean"},"microsoft_teams_enabled":{"nullable":true,"type":"boolean"},"agentic_memory_enabled":{"nullable":true,"type":"boolean"},"team_id":{"nullable":true,"type":"string"},"thread_id":{"nullable":true,"type":"string"},"folder_id":{"nullable":true,"type":"string"},"pinned_at":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"last_run_at":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"updated_by":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"nullable":true,"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false},"latest_build":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false},"integration_configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"integration_id":{"type":"string"},"integration_type":{"type":"string"},"integration_name":{"type":"string"},"created_at":{"type":"string"},"icon_url":{"nullable":true,"type":"string"},"is_connected":{"type":"boolean"}},"required":["id","integration_id","integration_type","integration_name","created_at"],"additionalProperties":false}},"user_triggers":{"type":"object","properties":{"slack_mention":{"type":"boolean"},"slack_channel":{"type":"boolean"},"teams_mention":{"type":"boolean"}},"required":["slack_mention","slack_channel","teams_mention"],"additionalProperties":false},"case_trigger_enabled":{"type":"boolean"},"case_trigger_has_conflict":{"type":"boolean"},"case_trigger_conflicting_agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"case_queue_name":{"nullable":true,"type":"string"}},"required":["id","name","slack_enabled","microsoft_teams_enabled","agentic_memory_enabled","team_id","thread_id","created_at","updated_at","last_run_at","latest_build","integration_configs"],"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}}}},"403":{"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/revisions/{build\_id}

> Deprecated: use GET /v1/agents/{agent\_id}/revisions/{build\_id} instead. Scheduled for removal on 2026-05-22.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Revisions","description":"Create and manage agent revisions — the underlying Setup for an Assignment"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"paths":{"/v1/revisions/{build_id}":{"get":{"tags":["Revisions"],"description":"Deprecated: use GET /v1/agents/{agent_id}/revisions/{build_id} instead. Scheduled for removal on 2026-05-22.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"build_id","required":true,"description":"Build ID"}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","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}/revisions

> List revisions for an agent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Revisions","description":"Create and manage agent revisions — the underlying Setup for an Assignment"}],"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}/revisions":{"get":{"operationId":"listAgentRevisions","tags":["Revisions"],"description":"List revisions for an agent.","parameters":[{"schema":{"default":20,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of revisions per page (1-100, default 20)"},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false,"description":"Number of revisions to skip"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"agent_id","required":true,"description":"The agent's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"builds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"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/agents/{agent\_id}/revisions

> Create a new revision for an existing agent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Revisions","description":"Create and manage agent revisions — the underlying Setup for an Assignment"}],"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}/revisions":{"post":{"operationId":"createRevision","tags":["Revisions"],"description":"Create a new revision for an existing agent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Build name"},"config":{"description":"Build configuration (latest schema version only; legacy v1 configs are not accepted)","type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"description":"Model configuration for each capability the agent uses"},"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"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"]}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"]}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"]}}},"additionalProperties":{}}},"required":["models","input"],"description":"Agent configuration payload"}},"required":["version","data"]},"handover_target_ids":{"description":"Agent IDs that this agent can hand work off to","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"source_build_id":{"description":"Build ID to copy integrations and case queue links from","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["name"]}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"agent_id","required":true,"description":"The agent's unique identifier"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false},"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"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}}}},"403":{"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}}}}}}}}}
```

#### Update a Build

## PATCH /v1/revisions/{build\_id}

> Update a revision's configuration, name, description, or handover targets. Returns the updated revision.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Revisions","description":"Create and manage agent revisions — the underlying Setup for an Assignment"}],"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/revisions/{build_id}":{"patch":{"operationId":"updateRevision","tags":["Revisions"],"description":"Update a revision's configuration, name, description, or handover targets. Returns the updated revision.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"description":"Build configuration object","type":"object","additionalProperties":{}},"handoverTargetIds":{"description":"Agent IDs that this agent can hand over work to","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"revision_name":{"description":"Optional user-defined name for this revision. Pass null to clear.","nullable":true,"type":"string","minLength":1,"maxLength":80},"revision_description":{"description":"Optional user-defined description for this revision. Pass null to clear.","nullable":true,"type":"string","maxLength":500}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"build_id","required":true,"description":"The build's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"copilot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"revision_name":{"nullable":true,"type":"string"},"revision_description":{"nullable":true,"type":"string"},"config":{"nullable":true,"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"nullable":true,"type":"number","minimum":0,"maximum":2},"max_output_tokens":{"nullable":true,"type":"number","minimum":0,"exclusiveMinimum":true},"top_p":{"nullable":true,"type":"number","minimum":0,"maximum":1},"store":{"nullable":true,"type":"boolean"},"tools":{},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}]},"text":{"nullable":true,"type":"object","properties":{"format":{"nullable":true,"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}]}},"additionalProperties":false},"files":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"nullable":true,"type":"array","items":{"type":"string"}}},"required":["model","tools","input","files","skills"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"],"description":"Schema version discriminator — must be \"v2\" for the current schema"},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["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","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"],"description":"Claude model identifier used for the primary agent loop"}},"required":["model"],"additionalProperties":false,"description":"Primary Claude agent model configuration"},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"],"description":"Provider backing the browsing/computer-use model"},"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"],"description":"Model identifier for the browsing provider"}},"required":["provider","model"],"additionalProperties":false,"description":"Browsing/computer-use model configuration"}},"required":["agent","browsing"],"additionalProperties":false,"description":"Model configuration for each capability the agent uses"},"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":{"nullable":true,"type":"string","enum":["low","high","auto"]},"file_id":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"nullable":true,"type":"string","enum":["message"]}},"required":["role","content"],"additionalProperties":false}}],"description":"Initial agent instructions — either a single system prompt string or a list of structured messages"},"files":{"default":[],"description":"IDs of team files that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"skills":{"default":[],"description":"IDs of skills (team or system) that should be available to the agent","nullable":true,"type":"array","items":{"type":"string"}},"plugins":{"default":[],"description":"Plugins to load — either a built-in plugin name (e.g. \"code-review\") or a GitHub URL (e.g. \"https://github.com/owner/repo\")","nullable":true,"type":"array","items":{"type":"string"}},"subAgents":{"default":[],"description":"IDs of other assignments (agents in the same team) to expose to this assignment as Claude Code subagents. Each sub-assignment runs with its own SOP and connections; the parent can delegate to them via the Agent tool.","nullable":true,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"options":{"description":"Optional runtime options controlling how the agent executes","type":"object","properties":{"browserProvider":{"description":"Browser infrastructure provider","type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"description":"ID of the evaluation schema to apply to runs of this agent","type":"string"},"benchmarkExpectedOutcomes":{"description":"Expected outcomes used when running benchmark scenarios","type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the expected outcome"},"criteria":{"type":"string","description":"Pass/fail criteria used to evaluate the outcome"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":{}}},"required":["models","input","files","skills","plugins","subAgents"],"additionalProperties":false,"description":"Agent configuration payload"}},"required":["version","data"],"additionalProperties":false}]},"status":{"nullable":true,"type":"string"},"revision_number":{"nullable":true,"type":"number"},"parent_build_id":{"nullable":true,"type":"string"},"created_by":{"nullable":true,"type":"string"},"created_by_name":{"nullable":true,"type":"string"},"created_at":{"nullable":true,"type":"string"},"updated_at":{"nullable":true,"type":"string"},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false}}},"required":["id","copilot_id","agent_id","name","config","status","revision_number","parent_build_id","created_by","created_at","updated_at"],"additionalProperties":false,"description":"The updated build"}},"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}}}},"403":{"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}}}}}}}}}
```

***

### Folders

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

#### List Folders

## GET /v1/agent-folders

> List all agent folders for the authenticated team.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agent Folders","description":"Organize agents (Assignments in the Duvo UI) into folders"}],"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/agent-folders":{"get":{"operationId":"listAgentFolders","tags":["Agent Folders"],"description":"List all agent folders for the authenticated team.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"Unique folder identifier"},"name":{"type":"string","description":"Folder display name"},"team_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"ID of the team that owns the folder"},"parent_folder_id":{"nullable":true,"description":"Parent folder ID, or null if this is a root folder","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"updated_at":{"type":"string","description":"ISO 8601 last-update timestamp"},"agent_count":{"type":"number","description":"Number of agents directly inside this folder"},"subfolder_count":{"type":"number","description":"Number of direct subfolders inside this folder"}},"required":["id","name","team_id","parent_folder_id","created_at","updated_at","agent_count","subfolder_count"],"additionalProperties":false},"description":"Agent folders owned by the authenticated team"}},"required":["folders"],"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 a Folder

## POST /v1/agent-folders

> Create a new agent folder.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agent Folders","description":"Organize agents (Assignments in the Duvo UI) into folders"}],"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/agent-folders":{"post":{"operationId":"createAgentFolder","tags":["Agent Folders"],"description":"Create a new agent folder.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable folder name"},"parent_folder_id":{"nullable":true,"description":"Parent folder ID for nested folders. Omit or null to create at the root level.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"required":["name"]}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"Unique folder identifier"},"name":{"type":"string","description":"Human-readable folder name"},"team_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"Team that owns the folder"},"parent_folder_id":{"nullable":true,"description":"Parent folder ID, or null if at the root level","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"updated_at":{"type":"string","description":"ISO 8601 last-updated timestamp"}},"required":["id","name","team_id","parent_folder_id","created_at","updated_at"],"additionalProperties":false}},"required":["folder"],"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}}}}}}}}}
```

#### Update a Folder

## PATCH /v1/agent-folders/{folder\_id}

> Rename an agent folder or move it to a new parent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agent Folders","description":"Organize agents (Assignments in the Duvo UI) into folders"}],"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/agent-folders/{folder_id}":{"patch":{"operationId":"updateAgentFolder","tags":["Agent Folders"],"description":"Rename an agent folder or move it to a new parent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New folder name","type":"string","minLength":1,"maxLength":100},"parent_folder_id":{"description":"New parent folder ID. Pass null to move the folder to the root level.","nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"folder_id","required":true,"description":"The folder's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"Unique folder identifier"},"name":{"type":"string","description":"Human-readable folder name"},"team_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"Team that owns the folder"},"parent_folder_id":{"nullable":true,"description":"Parent folder ID, or null if at the root level","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"created_at":{"type":"string","description":"ISO 8601 creation timestamp"},"updated_at":{"type":"string","description":"ISO 8601 last-updated timestamp"}},"required":["id","name","team_id","parent_folder_id","created_at","updated_at"],"additionalProperties":false}},"required":["folder"],"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}}}}}}}}}
```

#### Delete a Folder

## DELETE /v1/agent-folders/{folder\_id}

> Delete an agent folder. If the folder contains assignments or subfolders, pass \`force=true\` to delete it and move the contained assignments to the root level.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agent Folders","description":"Organize agents (Assignments in the Duvo UI) into folders"}],"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/agent-folders/{folder_id}":{"delete":{"operationId":"deleteAgentFolder","tags":["Agent Folders"],"description":"Delete an agent folder. If the folder contains assignments or subfolders, pass `force=true` to delete it and move the contained assignments to the root level.","parameters":[{"schema":{"type":"string"},"in":"query","name":"force","required":false,"description":"Pass 'true' to delete a folder that still contains assignments or subfolders. Any contained assignments will be moved to the root level."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"folder_id","required":true,"description":"The folder's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success"}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Short error message"},"message":{"description":"Human-readable error detail","type":"string"},"has_contents":{"description":"True when the folder still contains assignments or subfolders","type":"boolean"},"agent_count":{"description":"Number of assignments that would be moved to the root level if force=true were passed","type":"number"}},"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}}}}}}}}}
```

#### Move Assignments into a Folder

***

### Connections

Connections represent OAuth accounts or credentials that your assignments use to access external services. You can manage existing connections and create new ones programmatically.

**Connection types and how to create them:**

* **Native OAuth** (Gmail, Google Sheets, Outlook, Google Calendar, etc.) — Use [Start Native OAuth Connection](#start-native-oauth-connection)
* **Composio OAuth** (Slack, HubSpot, Zendesk, Asana, etc.) — Use [Start Composio Connection](#start-composio-connection) then [Finalize Composio Connection](#finalize-composio-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.

## GET /v1/connections

> List the authenticated user's connections (connected integration instances) for the current team. Includes team-shared instances visible to the caller when the org-level Connections sharing setting is on. Filter by integration type with the \`type\` query parameter.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections":{"get":{"operationId":"listConnections","tags":["Connections"],"description":"List the authenticated user's connections (connected integration instances) for the current team. Includes team-shared instances visible to the caller when the org-level Connections sharing setting is on. Filter by integration type with the `type` query parameter.","parameters":[{"schema":{"type":"string"},"in":"query","name":"type","required":false},{"schema":{"default":100,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"integrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"provider":{"type":"string"},"user_id":{"nullable":true,"type":"string"},"team_id":{"type":"string"},"server_url":{"type":"string"},"transport_type":{"type":"string","enum":["stdio","sse","http"]},"auth_method":{"nullable":true,"type":"string"},"composio_mcp_id":{"default":null,"nullable":true,"type":"string"},"custom_integration_id":{"nullable":true,"type":"string"},"icon_url":{"nullable":true,"type":"string"},"oauth_provider":{"nullable":true,"type":"string"},"oauth_scopes":{"nullable":true,"type":"array","items":{"type":"string"}},"has_headers":{"type":"boolean"},"has_oauth_tokens":{"type":"boolean"},"integration_id":{"nullable":true,"type":"string"},"shared":{"type":"boolean"},"created_by":{"nullable":true,"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","type","provider","user_id","team_id","composio_mcp_id","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["integrations","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}}}}}}}}}
```

#### Get a Connection

## GET /v1/connections/{connection\_id}

> Get one of your connections by ID.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/{connection_id}":{"get":{"operationId":"getConnection","tags":["Connections"],"description":"Get one of your connections by ID.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"connection_id","required":true,"description":"Connection ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"provider":{"type":"string"},"user_id":{"nullable":true,"type":"string"},"team_id":{"type":"string"},"server_url":{"type":"string"},"transport_type":{"type":"string","enum":["stdio","sse","http"]},"auth_method":{"nullable":true,"type":"string"},"composio_mcp_id":{"default":null,"nullable":true,"type":"string"},"custom_integration_id":{"nullable":true,"type":"string"},"icon_url":{"nullable":true,"type":"string"},"oauth_provider":{"nullable":true,"type":"string"},"oauth_scopes":{"nullable":true,"type":"array","items":{"type":"string"}},"has_headers":{"type":"boolean"},"has_oauth_tokens":{"type":"boolean"},"integration_id":{"nullable":true,"type":"string"},"shared":{"type":"boolean"},"created_by":{"nullable":true,"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","type","provider","user_id","team_id","composio_mcp_id","created_at","updated_at"],"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}}}},"403":{"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}}}}}}}}}
```

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

## GET /v1/connections/{connection\_id}/credentials

> Get the header keys configured for a connection. Sensitive values (api keys, tokens, passwords) are returned as empty strings — the response only reveals which credential fields are set, never their values.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/{connection_id}/credentials":{"get":{"operationId":"getConnectionCredentials","tags":["Connections"],"description":"Get the header keys configured for a connection. Sensitive values (api keys, tokens, passwords) are returned as empty strings — the response only reveals which credential fields are set, never their values.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"connection_id","required":true,"description":"Connection ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"headers":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","headers"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"403":{"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 Connection

Creates a user-provided connection (custom MCP server with a URL and optional credential headers). For OAuth-based connections (native providers, Composio, or OAuth MCP servers), use the dedicated OAuth endpoints below instead.

## POST /v1/connections

> Create a new user-provided connection (custom MCP server) for the current team. OAuth-based integrations (native, composio) require an interactive browser flow — start them with the dedicated OAuth endpoints (\`/v1/connections/oauth/native/:provider/start\`, \`/v1/connections/oauth/mcp/start\`, or \`/v1/connections/composio/start\`) instead of calling this endpoint directly.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections":{"post":{"operationId":"createConnection","tags":["Connections"],"description":"Create a new user-provided connection (custom MCP server) for the current team. OAuth-based integrations (native, composio) require an interactive browser flow — start them with the dedicated OAuth endpoints (`/v1/connections/oauth/native/:provider/start`, `/v1/connections/oauth/mcp/start`, or `/v1/connections/composio/start`) instead of calling this endpoint directly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"server_url":{"type":"string","format":"uri"},"type":{"default":"custom_mcp","type":"string"},"provider":{"type":"string","enum":["user"]},"auth_method":{"type":"string","enum":["url","apikey","headers","oauth"]},"custom_integration_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"headers":{"type":"object","properties":{"plaintext":{"type":"object","additionalProperties":{"type":"string"}},"secret":{"type":"object","additionalProperties":{"type":"string"}}}}},"required":["name","provider","auth_method"]}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"provider":{"type":"string"},"user_id":{"nullable":true,"type":"string"},"team_id":{"type":"string"},"server_url":{"type":"string"},"transport_type":{"type":"string","enum":["stdio","sse","http"]},"auth_method":{"nullable":true,"type":"string"},"composio_mcp_id":{"default":null,"nullable":true,"type":"string"},"custom_integration_id":{"nullable":true,"type":"string"},"icon_url":{"nullable":true,"type":"string"},"oauth_provider":{"nullable":true,"type":"string"},"oauth_scopes":{"nullable":true,"type":"array","items":{"type":"string"}},"has_headers":{"type":"boolean"},"has_oauth_tokens":{"type":"boolean"},"integration_id":{"nullable":true,"type":"string"},"shared":{"type":"boolean"},"created_by":{"nullable":true,"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","type","provider","user_id","team_id","composio_mcp_id","created_at","updated_at"],"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}}}}}}}}}
```

#### Update a Connection

## PATCH /v1/connections/{connection\_id}

> Update an existing connection. For sensitive header values, sending an empty string keeps the existing value; send a new value to overwrite. Toggling \`shared\` moves the connection between personal and team-shared.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/{connection_id}":{"patch":{"operationId":"updateConnection","tags":["Connections"],"description":"Update an existing connection. For sensitive header values, sending an empty string keeps the existing value; send a new value to overwrite. Toggling `shared` moves the connection between personal and team-shared.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"server_url":{"type":"string","format":"uri"},"auth_method":{"type":"string","enum":["url","oauth","apikey","headers"]},"headers":{"nullable":true,"type":"object","properties":{"plaintext":{"type":"object","additionalProperties":{"type":"string"}},"secret":{"type":"object","additionalProperties":{"type":"string"}}}},"composio_mcp_id":{"nullable":true,"type":"string"},"shared":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"connection_id","required":true,"description":"Connection ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"provider":{"type":"string"},"user_id":{"nullable":true,"type":"string"},"team_id":{"type":"string"},"server_url":{"type":"string"},"transport_type":{"type":"string","enum":["stdio","sse","http"]},"auth_method":{"nullable":true,"type":"string"},"composio_mcp_id":{"default":null,"nullable":true,"type":"string"},"custom_integration_id":{"nullable":true,"type":"string"},"icon_url":{"nullable":true,"type":"string"},"oauth_provider":{"nullable":true,"type":"string"},"oauth_scopes":{"nullable":true,"type":"array","items":{"type":"string"}},"has_headers":{"type":"boolean"},"has_oauth_tokens":{"type":"boolean"},"integration_id":{"nullable":true,"type":"string"},"shared":{"type":"boolean"},"created_by":{"nullable":true,"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","type","provider","user_id","team_id","composio_mcp_id","created_at","updated_at"],"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}}}},"403":{"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}}}}}}}}}
```

#### Delete a Connection

## DELETE /v1/connections/{connection\_id}

> Delete a connection (disconnects the user's connection and removes any triggers bound to it).

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/{connection_id}":{"delete":{"operationId":"deleteConnection","tags":["Connections"],"description":"Delete a connection (disconnects the user's connection and removes any triggers bound to it).","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"connection_id","required":true,"description":"Connection ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"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}}}},"403":{"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}}}}}}}}}
```

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

## POST /v1/connections/oauth/native/{provider}/start

> Start an OAuth-based connection with a native provider (Gmail, Google Sheets, Outlook, etc.). Returns an authorization URL that must be opened in a browser by a human end-user; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional \`return\_url\` (or the Duvo dashboard if none is provided). Poll \`/v1/connections\` to detect the new connection.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/oauth/native/{provider}/start":{"post":{"operationId":"startNativeOAuth","tags":["Connections"],"description":"Start an OAuth-based connection with a native provider (Gmail, Google Sheets, Outlook, etc.). Returns an authorization URL that must be opened in a browser by a human end-user; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional `return_url` (or the Duvo dashboard if none is provided). Poll `/v1/connections` to detect the new connection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"return_url":{"description":"Where to send the user's browser after consent completes. Accepts an absolute URL on a domain Duvo allows, or a path relative to the Duvo frontend (e.g. `/integrations/gmail`).","type":"string"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"provider","required":true,"description":"OAuth provider slug (e.g. 'google', 'gmail', 'googlesheets', 'outlook'). Must match a configured native OAuth provider."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"authorization_url":{"type":"string","description":"OAuth provider authorization URL to open in a browser"}},"required":["authorization_url"],"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}}}}}}}}}
```

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

## POST /v1/connections/oauth/mcp/start

> Start an OAuth-based connection with a remote MCP server using Dynamic Client Registration. Returns an authorization URL the user must open in a browser; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional \`returnUrl\`.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/oauth/mcp/start":{"post":{"operationId":"authorizeMcpOAuth","tags":["Connections"],"description":"Start an OAuth-based connection with a remote MCP server using Dynamic Client Registration. Returns an authorization URL the user must open in a browser; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional `returnUrl`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mcp_server_url":{"type":"string","format":"uri","description":"URL of the MCP server requiring OAuth."},"name":{"type":"string","minLength":1,"description":"Human-readable name to display for the connection."},"custom_integration_id":{"description":"Optional ID of a custom integration this connection should be associated with.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"return_url":{"description":"Where to send the user's browser after consent completes. Accepts an absolute URL on a domain Duvo allows, or a path relative to the Duvo frontend (e.g. `/integrations/slack`).","type":"string"},"integration_type":{"description":"Optional integration type label.","type":"string"}},"required":["mcp_server_url","name"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"authorization_url":{"type":"string","description":"OAuth provider authorization URL to open in a browser"}},"required":["authorization_url"],"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}}}}}}}}}
```

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

## POST /v1/connections/oauth/mcp/check

> Probe an MCP server URL to discover whether it supports OAuth Dynamic Client Registration. Returns the authorization endpoint and required scopes when supported. Useful as a precursor to \`/v1/connections/oauth/mcp/start\` or \`/v1/connections\`. Performs no writes.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/oauth/mcp/check":{"post":{"operationId":"checkMcpOAuth","tags":["Connections"],"description":"Probe an MCP server URL to discover whether it supports OAuth Dynamic Client Registration. Returns the authorization endpoint and required scopes when supported. Useful as a precursor to `/v1/connections/oauth/mcp/start` or `/v1/connections`. Performs no writes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mcp_server_url":{"type":"string","format":"uri","description":"URL of the MCP server to probe for OAuth support."}},"required":["mcp_server_url"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"supports_dcr":{"type":"boolean","description":"True if the MCP server advertises OAuth Dynamic Client Registration"},"authorization_endpoint":{"description":"OAuth authorization endpoint advertised by the MCP server, when discoverable","type":"string"},"scopes":{"description":"Scopes the MCP server requests during authorization","type":"array","items":{"type":"string"}}},"required":["supports_dcr"],"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}}}}}}}}}
```

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

## Probe an MCP server for available tools

> Probe an MCP server URL and list the tools it exposes. Useful as a dry-run before creating a connection — verifies the URL is reachable, that authentication headers (if any) are correct, and surfaces the tool catalog. Performs no writes; sits alongside \`/v1/connections/oauth/mcp/check\` (which probes the same URL for OAuth support).

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/mcp/probe":{"post":{"operationId":"probeMcpServer","summary":"Probe an MCP server for available tools","tags":["Connections"],"description":"Probe an MCP server URL and list the tools it exposes. Useful as a dry-run before creating a connection — verifies the URL is reachable, that authentication headers (if any) are correct, and surfaces the tool catalog. Performs no writes; sits alongside `/v1/connections/oauth/mcp/check` (which probes the same URL for OAuth support).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"server_url":{"type":"string","format":"uri","description":"MCP server URL to test"},"headers":{"description":"Optional HTTP headers for authentication","type":"object","additionalProperties":{"type":"string"}}},"required":["server_url"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":{}}},"required":["name"],"additionalProperties":false}},"error":{"type":"string"}},"required":["success"],"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}}}}}}}}}
```

#### Start Composio Connection

Starts a Composio-backed connection. For OAuth-based toolkits (Slack, HubSpot, Zendesk, Asana, etc.), returns a `redirect_url` you open in the user's browser to complete the consent flow. For non-OAuth toolkits (API key, Bearer token), the connection may finalize synchronously with `redirect_url: null`. After the flow completes, call [Finalize Composio Connection](#finalize-composio-connection) to provision the connection in Duvo.

## POST /v1/connections/composio/start

> 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 \`/v1/connections/composio/finalize\` to provision the corresponding Duvo connection.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/composio/start":{"post":{"operationId":"startComposioConnection","tags":["Connections"],"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 `/v1/connections/composio/finalize` to provision the corresponding Duvo connection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auth_config_id":{"type":"string","minLength":1,"description":"Composio auth-config ID for the toolkit. Obtain it from Composio's auth-config catalog or by listing existing configs."},"callback_url":{"type":"string","format":"uri","description":"Where to send the user's browser after they finish the Composio consent screen. Must be an absolute URL."},"auth_scheme":{"description":"Composio auth scheme (e.g. 'OAUTH2', 'API_KEY', 'BEARER_TOKEN'). Required when supplying non-OAuth credentials in `auth_fields`.","type":"string"},"auth_fields":{"description":"Auth field values keyed by field name. For OAuth, these are passed in `connection.data`; for API_KEY/BEARER_TOKEN/etc., these are passed via `connection.state` with the corresponding `auth_scheme`.","type":"object","additionalProperties":{"type":"string"}}},"required":["auth_config_id","callback_url"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"redirect_url":{"nullable":true,"description":"Browser URL the user must visit to complete authorization. Null when the connection was completed synchronously (e.g. for API_KEY auth that did not require a browser flow).","type":"string"},"status":{"nullable":true,"description":"Composio connection status (e.g. 'INITIATED', 'ACTIVE', 'FAILED').","type":"string"},"connected_account_id":{"type":"string","minLength":1,"description":"Composio connected-account ID created by this request. Always present — required by `/v1/connections/composio/finalize` to bind the new connection to the exact account."}},"required":["redirect_url","status","connected_account_id"],"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}}}},"403":{"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}}}}}}}}}
```

#### Finalize Composio Connection

Completes a Composio connection after the start step. Call this once the user has finished the OAuth flow (or immediately after a synchronous non-OAuth start). Pass the `connected_account_id` returned by [Start Composio Connection](#start-composio-connection).

## POST /v1/connections/composio/finalize

> Finalize a Composio-backed connection after the start step (\`/v1/connections/composio/start\`) has produced a \`connected\_account\_id\`. Provisions a Composio MCP server bound to that account and persists the connection on the team. Works for both OAuth and non-OAuth start flows. Stale or invalid \`connected\_account\_id\`, missing app, or rejected upstream input surfaces as a 4xx via \`composioErrorFor\`; only genuinely unexpected upstream/persistence failures return 5xx.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Connections","description":"Manage your connected integrations"}],"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/connections/composio/finalize":{"post":{"operationId":"connectComposioIntegration","tags":["Connections"],"description":"Finalize a Composio-backed connection after the start step (`/v1/connections/composio/start`) has produced a `connected_account_id`. Provisions a Composio MCP server bound to that account and persists the connection on the team. Works for both OAuth and non-OAuth start flows. Stale or invalid `connected_account_id`, missing app, or rejected upstream input surfaces as a 4xx via `composioErrorFor`; only genuinely unexpected upstream/persistence failures return 5xx.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app":{"type":"string","minLength":1,"description":"Composio app slug (e.g. 'slack', 'googlesheets'). Must match a Composio toolkit configured for the team."},"integration_name":{"type":"string","minLength":1,"description":"Human-readable name to display for the connection."},"connected_account_id":{"type":"string","minLength":1,"description":"Composio connected-account ID returned by `/v1/connections/composio/start`. Used to bind this finalize call to the exact account the user just authorized; without it the wrong account could be picked when the team has multiple Composio accounts for the same app."}},"required":["app","integration_name","connected_account_id"]}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"integration_id":{"type":"string"},"mcp_url":{"type":"string"}},"required":["integration_id","mcp_url"],"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}}}},"403":{"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}}}}}}}}}
```

***

### Schedules

#### List Schedules for an Assignment

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

> List all schedules configured for an agent. Returns the schedules you own on this agent.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Schedules","description":"List schedules configured for an agent (Assignment in the Duvo UI)"}],"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}/schedules":{"get":{"operationId":"listAgentSchedules","tags":["Schedules"],"description":"List all schedules configured for an agent. Returns the schedules you own on this agent.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"agent_id","required":true,"description":"The agent's unique identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"build_id":{"type":"string"},"agent_id":{"type":"string"},"user_id":{"type":"string"},"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["every_5_minutes","every_15_minutes","hourly","daily","workday","weekly","monthly","custom"]},"time":{"nullable":true,"type":"string"},"timezone":{"type":"string"},"day":{"nullable":true,"type":"string"},"day_of_month":{"nullable":true,"type":"number"},"cron":{"nullable":true,"type":"string"},"source":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"recurring":{"nullable":true,"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_name":{"nullable":true,"type":"string"},"user_email":{"nullable":true,"type":"string"}},"required":["id","build_id","agent_id","user_id","enabled","frequency","time","timezone","day","day_of_month","cron","source","task","recurring","created_at","updated_at"],"additionalProperties":false},"description":"Schedules the authenticated user owns on this agent"}},"required":["schedules"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"403":{"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](/running-assignments/running-assignments-via-api.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.duvo.ai/running-assignments/creating-assignments-via-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.