# Runs

Start, monitor, and manage agent runs

## POST /v1/runs

> Start a new agent run. Returns immediately with run info - does not wait for completion.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs":{"post":{"tags":["Runs"],"description":"Start a new agent run. Returns immediately with run info - does not wait for completion.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","description":"The agent ID to run"},"message":{"type":"string","description":"Optional initial message to start the run with (e.g. a trigger payload or user instruction)"},"sandbox_id":{"type":"string","description":"Optional sandbox ID with pre-uploaded files"},"webhook_url":{"type":"string","format":"uri","description":"Webhook URL to POST events to (human_request, run_completed, run_failed, run_interrupted)"}},"required":["agent_id"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"build_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"source":{"type":"string","nullable":true},"sandbox_id":{"type":"string","nullable":true,"description":"The sandbox ID for this run"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"human_in_the_loop_enabled":{"type":"boolean","description":"Whether this agent can request human input during execution"}},"required":["id","agent_id","build_id","status","source","sandbox_id","started_at","completed_at","created_at","updated_at","human_in_the_loop_enabled"],"additionalProperties":false}},"required":["run"],"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 /v1/runs/{run\_id}

> Get information about an agent run. Can be polled to check status.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs/{run_id}":{"get":{"tags":["Runs"],"description":"Get information about an agent run. Can be polled to check status.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"run_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"build_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"source":{"type":"string","nullable":true},"sandbox_id":{"type":"string","nullable":true,"description":"The sandbox ID for this run"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"human_in_the_loop_enabled":{"type":"boolean","description":"Whether this agent can request human input during execution"}},"required":["id","agent_id","build_id","status","source","sandbox_id","started_at","completed_at","created_at","updated_at","human_in_the_loop_enabled"],"additionalProperties":false,"nullable":true},"pending_human_request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"type":{"type":"string","enum":["approval","question"],"description":"Type of human request: 'approval' for yes/no decisions, 'question' for structured questions with optional predefined answers"},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"header":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"description":{"type":"string"}},"required":["label"],"additionalProperties":false}},"multi_select":{"type":"boolean"}},"required":["question"],"additionalProperties":false},"description":"For 'question' type requests, the structured questions with optional predefined answer options"}},"required":["id","title","description","created_at","type"],"additionalProperties":false,"nullable":true}},"required":["run"],"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 /v1/runs/{run\_id}/messages

> Get paginated messages for an agent run. Messages are returned in chronological order.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs/{run_id}/messages":{"get":{"tags":["Runs"],"description":"Get paginated messages for an agent run. Messages are returned in chronological order.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"in":"query","name":"limit","required":false,"description":"Number of messages per page (1-50, default 20)"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of messages to skip"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"run_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"role":{"type":"string"},"timestamp":{"type":"string"},"text_content":{"type":"string"},"tool_call":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"arguments":{"type":"object","additionalProperties":{}}},"required":["id","name"],"additionalProperties":false},"tool_result":{"type":"object","properties":{"tool_call_id":{"type":"string"},"result":{},"error":{"type":"string"}},"required":["tool_call_id"],"additionalProperties":false}},"required":["id","type","role","timestamp"],"additionalProperties":false}},"total":{"type":"number","description":"Total number of messages for the run"},"limit":{"type":"number","description":"Number of messages per page"},"offset":{"type":"number","description":"Number of messages skipped"}},"required":["messages","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}}}},"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}}}}}}}}}
```

## POST /v1/runs/{run\_id}/messages

> Post a message to an agent run. This will persist the message and resume the agent execution if the run is in a resumable state (waiting, completed, or interrupted).

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs/{run_id}/messages":{"post":{"tags":["Runs"],"description":"Post a message to an agent run. This will persist the message and resume the agent execution if the run is in a resumable state (waiting, completed, or interrupted).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"description":"The message content to send to the agent"}},"required":["message"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"run_id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"role":{"type":"string"},"timestamp":{"type":"string"},"text_content":{"type":"string"}},"required":["id","type","role","timestamp","text_content"],"additionalProperties":false}},"required":["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}}}}}}}}}
```

## POST /v1/runs/{run\_id}/human-requests/{request\_id}/respond

> Respond to a human-in-the-loop request. Use 'approved' (true/false) for approval-type requests, or 'answers' ({question: answer}) for question-type requests. Only works when the run is in 'waiting' status.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs/{run_id}/human-requests/{request_id}/respond":{"post":{"tags":["Runs"],"description":"Respond to a human-in-the-loop request. Use 'approved' (true/false) for approval-type requests, or 'answers' ({question: answer}) for question-type requests. Only works when the run is in 'waiting' status.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"answers":{"type":"object","additionalProperties":{"type":"string"},"description":"For question-type requests: a map of question text to answer. Multi-select answers should be comma-separated."},"approved":{"type":"boolean","description":"For approval-type requests: true to approve, false to deny"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"run_id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"request_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"human_request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"run_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"response":{"type":"string","nullable":true},"responded_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","run_id","title","description","response","responded_at","created_at"],"additionalProperties":false}},"required":["human_request"],"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}}}}}}}}}
```

## POST /v1/runs/{run\_id}/stop

> Stop an agent run. No-op if the run is not currently running.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Start, monitor, and manage agent runs"}],"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/runs/{run_id}/stop":{"post":{"tags":["Runs"],"description":"Stop an agent run. No-op if the run is not currently running.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"run_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"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}}}},"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}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}}}}
```