Duvo Ai Runs API
Start, monitor, and manage agent runs (Runs in the Duvo UI)
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/duvo-ai-runs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Duvo Public Agent Folders Runs API
description: Public API for programmatic access to Duvo. Authenticate with API keys created in the Duvo dashboard.
version: 1.0.0
servers:
- url: https://api.duvo.ai
description: Production server
tags:
- name: Runs
description: Start, monitor, and manage agent runs (Runs in the Duvo UI)
paths:
/v2/agent/{agentId}/runs/{runId}/evaluation:
get:
operationId: getRunEvaluation
tags:
- Runs
description: Get the latest evaluation analysis for a specific agent run (Run).
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Agent ID)
- schema:
type: string
format: uuid
in: path
name: runId
required: true
description: The run's unique identifier (Run ID)
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
data:
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
created_at:
type: string
run_id:
type: string
format: uuid
source:
type:
- string
- 'null'
output:
type: object
properties:
schemaId:
type: string
schemaVersion:
type: string
data:
type: object
additionalProperties:
anyOf:
- type: boolean
- type: string
- type:
- string
- 'null'
enum:
- null
required:
- data
additionalProperties: false
required:
- id
- created_at
- run_id
- source
- output
additionalProperties: false
required:
- data
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
summary: Get Run Evaluation
/v2/runs/{run_id}:
get:
operationId: getRun
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
description: The run's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
run:
description: The run details, or null if the run no longer exists
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
description: Unique run identifier
agent_id:
type: string
format: uuid
description: ID of the agent being run
build_id:
type: string
format: uuid
description: ID of the build being run
status:
type: string
description: Current run status
source:
description: How the run was initiated
type:
- string
- 'null'
sandbox_id:
description: The sandbox ID for this run
type:
- string
- 'null'
started_at:
description: ISO 8601 timestamp when the run started
type:
- string
- 'null'
completed_at:
description: ISO 8601 timestamp when the run completed
type:
- string
- 'null'
created_at:
type: string
description: ISO 8601 timestamp when the run was created
updated_at:
type: string
description: ISO 8601 timestamp when the run was last updated
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
pending_human_request:
description: The pending human request blocking the run, if any
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
description: Unique human-request identifier
title:
type: string
description: Short title for the request
description:
description: Longer description of the request
type:
- string
- 'null'
created_at:
type: string
description: ISO 8601 timestamp when the request was created
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:
description: For 'question' type requests, the structured questions with optional predefined answer options
type: array
items:
type: object
properties:
question:
type: string
description: The question being asked
header:
description: Short header for the question
type: string
options:
description: Predefined answer options
type: array
items:
type: object
properties:
label:
type: string
description: Display label for the option
description:
description: Optional explanation of what this option means
type: string
required:
- label
additionalProperties: false
multi_select:
description: Whether multiple options can be selected
type: boolean
required:
- question
additionalProperties: false
required:
- id
- title
- description
- created_at
- type
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
summary: Get Run
/v2/runs/{run_id}/messages:
post:
operationId: postRunMessage
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:
required: true
content:
application/json:
schema:
type: object
properties:
message:
type: string
minLength: 1
description: The message content to send to the agent
required:
- message
parameters:
- schema:
type: string
format: uuid
in: path
name: run_id
required: true
description: The run's unique identifier
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
id:
type: string
description: Unique message identifier
type:
type: string
description: Message type
role:
type: string
description: Sender role
timestamp:
type: string
description: ISO 8601 timestamp when the message was posted
text_content:
type: string
description: Plain text content of the message
required:
- id
- type
- role
- timestamp
- text_content
additionalProperties: false
description: The message that was posted to the run
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
summary: Post Run Message
get:
operationId: listRunMessages
tags:
- Runs
description: Get paginated messages for an agent run. Messages are returned in chronological order.
parameters:
- schema:
default: 20
type: integer
minimum: 1
maximum: 50
in: query
name: limit
required: false
description: Number of messages per page (1-50, default 20)
- schema:
type: integer
minimum: 0
maximum: 9007199254740991
in: query
name: offset
required: false
description: Number of messages to skip
- schema:
type: string
format: uuid
in: path
name: run_id
required: true
description: The run's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
type: object
properties:
id:
type: string
description: Unique message identifier
type:
type: string
description: Message type
role:
type: string
description: Sender role (e.g., user, assistant, tool)
timestamp:
type: string
description: ISO 8601 timestamp when the message was sent
text_content:
description: Plain text content of the message
type: string
tool_call:
description: Tool invocation details when role is assistant
type: object
properties:
id:
type: string
description: Tool call identifier
name:
type: string
description: Tool name being invoked
arguments:
description: Arguments passed to the tool
type: object
additionalProperties: {}
required:
- id
- name
additionalProperties: false
tool_result:
description: Tool result details when role is tool
type: object
properties:
tool_call_id:
type: string
description: ID of the tool call this result corresponds to
result:
description: Serialized tool output
error:
description: Error message if the tool invocation failed
type: string
required:
- tool_call_id
additionalProperties: false
required:
- id
- type
- role
- timestamp
additionalProperties: false
description: Messages for the run, in chronological order
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
summary: List Run Messages
/v2/runs/{run_id}/human-requests/{request_id}/respond:
post:
operationId: respondToHumanRequest
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:
required: true
content:
application/json:
schema:
type: object
properties:
answers:
description: 'For question-type requests: a map of question text to answer. Multi-select answers should be comma-separated.'
type: object
additionalProperties:
type: string
approved:
description: 'For approval-type requests: true to approve, false to deny'
type: boolean
parameters:
- schema:
type: string
format: uuid
in: path
name: run_id
required: true
description: The run's unique identifier
- schema:
type: string
format: uuid
in: path
name: request_id
required: true
description: The human request's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
human_request:
type: object
properties:
id:
type: string
format: uuid
description: Unique human-request identifier
run_id:
type: string
format: uuid
description: ID of the run this request belongs to
title:
type: string
description: Short title for the request
description:
description: Longer description of the request
type:
- string
- 'null'
response:
description: The response provided by the user
type:
- string
- 'null'
responded_at:
description: ISO 8601 timestamp when the user responded
type:
- string
- 'null'
created_at:
type: string
description: ISO 8601 timestamp when the request was created
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
summary: Respond To Human Request
/v2/runs/{run_id}/stop:
post:
operationId: stopRun
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
description: The run's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the stop request succeeded
message:
description: Optional human-readable detail
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
summary: Stop Run
/v2/teams/{teamId}/runs:
get:
operationId: listRuns
tags:
- Runs
description: List runs for the current team. Supports filtering by agent, user, queue, status, etc. Messages, evaluation data, and queue metadata are included where available.
parameters:
- schema:
default: 20
type: number
minimum: 1
maximum: 100
in: query
name: limit
required: false
description: Number of runs per page (1-100, default 20)
- schema:
type: number
minimum: 0
in: query
name: offset
required: fals
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvo-ai/refs/heads/main/openapi/duvo-ai-runs-api-openapi.yml