{"openapi":"3.1.0","info":{"title":"Duvo API","version":"2026-05-23","description":"Duvo API for approved customer workspaces. Use it to start and inspect agent runs, create durable queue cases, respond to human approval gates, connect MCP tools, and manage governed agent execution.","contact":{"name":"Duvo","url":"https://www.duvo.ai/contact"}},"servers":[{"url":"https://api.duvo.ai","description":"Duvo API"}],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":[]}],"paths":{"/v1/agents":{"post":{"operationId":"createAgent","summary":"Create or register an assignment-backed agent worker","tags":["Agents"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["agents:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/runs":{"post":{"operationId":"startRun","summary":"Start an agent run","tags":["Runs"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["runs:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartRunRequest"}}}},"responses":{"202":{"description":"Run accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/runs/{run_id}":{"get":{"operationId":"getRun","summary":"Inspect a run","tags":["Runs"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["runs:read"]}],"parameters":[{"$ref":"#/components/parameters/RunId"}],"responses":{"200":{"description":"Run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/runs/{run_id}/messages":{"get":{"operationId":"listRunMessages","summary":"List run messages, tool calls, files, approvals, and audit events","tags":["Runs"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["runs:read"]}],"parameters":[{"$ref":"#/components/parameters/RunId"}],"responses":{"200":{"description":"Run messages","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunMessage"}}}}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/runs/{run_id}/human-requests/{request_id}/respond":{"post":{"operationId":"respondToHumanRequest","summary":"Approve, reject, or answer a human approval request","tags":["Approvals"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["approvals:write"]}],"parameters":[{"$ref":"#/components/parameters/RunId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanRequestResponse"}}}},"responses":{"200":{"description":"Human request response accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/queues/{queue_id}/cases":{"post":{"operationId":"createQueueCase","summary":"Create a durable case in a case queue","tags":["Queues"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["queues:write"]}],"parameters":[{"$ref":"#/components/parameters/QueueId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCaseRequest"}}}},"responses":{"201":{"description":"Case created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueCase"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/sandboxes":{"post":{"operationId":"createSandbox","summary":"Request a governed execution sandbox","tags":["Sandboxes"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["sandboxes:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSandboxRequest"}}}},"responses":{"202":{"description":"Sandbox request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sandbox"}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}},"/v1/mcp":{"post":{"operationId":"callHostedMcp","summary":"Call the hosted Duvo MCP endpoint for an approved workspace","tags":["MCP"],"security":[{"BearerAuth":[]},{"OAuthClientCredentials":["mcp:call"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"MCP response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"workspace_token","description":"Workspace-issued bearer token."},"OAuthClientCredentials":{"type":"oauth2","description":"Scoped OAuth client credentials for enterprise workspaces where enabled.","flows":{"clientCredentials":{"tokenUrl":"https://api.duvo.ai/oauth/token","scopes":{"agents:write":"Create or register assignment-backed agents","runs:read":"Inspect runs, messages, files, tool calls, and audit events","runs:write":"Start, pause, resume, or replay runs","queues:write":"Create and update queue cases","approvals:write":"Respond to human approval requests","sandboxes:write":"Request governed execution sandboxes","mcp:call":"Call hosted Duvo MCP tools"}}}}},"parameters":{"RunId":{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},"RequestId":{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}},"QueueId":{"name":"queue_id","in":"path","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional idempotency key for safe retries of mutating requests."}},"responses":{"ErrorResponse":{"description":"JSON error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Agent":{"type":"object","required":["id","name","created_at"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"StartRunRequest":{"type":"object","required":["assignment_id"],"properties":{"assignment_id":{"type":"string"},"input":{"type":"object","additionalProperties":true},"queue_case_id":{"type":"string"},"idempotency_key":{"type":"string"}}},"Run":{"type":"object","required":["id","status","created_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","waiting_for_human","completed","failed","canceled"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"output":{"type":"object","additionalProperties":true}}},"RunMessage":{"type":"object","required":["id","type","created_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["message","tool_call","file","approval","audit_event"]},"created_at":{"type":"string","format":"date-time"},"content":{"type":"object","additionalProperties":true}}},"HumanRequestResponse":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject","answer"]},"answer":{"type":"string"},"note":{"type":"string"}}},"CreateCaseRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"input":{"type":"object","additionalProperties":true},"idempotency_key":{"type":"string"}}},"QueueCase":{"type":"object","required":["id","status","created_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","claimed","completed","failed"]},"created_at":{"type":"string","format":"date-time"}}},"CreateSandboxRequest":{"type":"object","required":["purpose"],"properties":{"purpose":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}}}},"Sandbox":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["requested","ready","closed"]}}},"Error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}