duvo.ai Agents API
Create and manage agents for automation workloads
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Agents 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: Agents
description: Create and manage agents for automation workloads
paths:
/v2/agent/{agentId}/eval-scores:
get:
operationId: getEvalScores
tags:
- Agents
description: Aggregate evaluation counts and flag distribution for an Assignment's Jobs since the given timestamp.
parameters:
- schema:
type: string
format: date-time
in: query
name: since
required: true
description: ISO 8601 timestamp; only Jobs evaluated after this are counted
- schema:
type: string
enum:
- all
- custom
in: query
name: scope
required: false
description: When 'custom', only counts Jobs scored against the target revision's custom rubrics, and only `custom__*` rubric flags. Defaults to 'all' (platform + custom rubrics).
- schema:
type: string
format: uuid
in: query
name: revision_id
required: false
description: Target a specific Assignment revision instead of the live revision. Only honoured when scope='custom' — non-custom scopes aggregate across all revisions. Defaults to the live revision when omitted.
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
total_evaluated:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
with_issues:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
flag_distribution:
type: array
items:
type: object
properties:
flag:
type: string
count:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
label:
nullable: true
type: string
required:
- flag
- count
additionalProperties: false
required:
- total_evaluated
- with_issues
- flag_distribution
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 Eval Scores
/v2/agents/{agentId}/eval-rubrics:
get:
operationId: getEvalRubrics
tags:
- Agents
description: 'List the evaluation rubrics a Run is scored against: the platform default rubrics plus the Agent-specific rubrics for a build. Defaults to the Agent''s live build; pass build_id to target the revision a specific Run ran against.'
parameters:
- schema:
type: string
format: uuid
in: query
name: build_id
required: false
description: Return rubrics for this specific build (the revision a Run ran against). Defaults to the agent's live build when omitted.
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
rubrics:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
title:
type: string
description:
type: string
sort_order:
type: number
deleted_at:
nullable: true
type: string
required:
- id
- slug
- title
- description
- sort_order
- deleted_at
additionalProperties: false
platform_rubrics:
type: array
items:
type: object
properties:
key:
type: string
label:
type: string
description:
type: string
cause:
type: string
required:
- key
- label
- description
- cause
additionalProperties: false
required:
- rubrics
- platform_rubrics
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 Eval Rubrics
post:
operationId: createEvalRubric
tags:
- Agents
description: Add one Agent-specific evaluation rubric to a build. A build may hold at most 5 custom rubrics; this fails with 409 once that ceiling is reached. Defaults to the Agent's live build; pass build_id to target a specific revision.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
minLength: 3
maxLength: 80
description: Short, human-readable Pass/Fail rubric title.
description:
type: string
minLength: 20
maxLength: 400
description: A 1-2 sentence Pass condition phrased as a question.
build_id:
description: Add the rubric to this build (revision). Defaults to the agent's live build when omitted.
type: string
format: uuid
required:
- title
- description
additionalProperties: false
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
rubric:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
title:
type: string
description:
type: string
sort_order:
type: number
deleted_at:
nullable: true
type: string
required:
- id
- slug
- title
- description
- sort_order
- deleted_at
additionalProperties: false
required:
- rubric
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
'409':
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: Create Eval Rubric
put:
operationId: replaceEvalRubrics
tags:
- Agents
description: Replace a build's entire Agent-specific evaluation rubric set in one call (at most 5 rubrics). Existing custom rubrics are removed and the supplied list becomes the new set; pass an empty array to clear them. Defaults to the Agent's live build; pass build_id to target a specific revision.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rubrics:
maxItems: 5
type: array
items:
type: object
properties:
title:
type: string
minLength: 3
maxLength: 80
description: Short, human-readable Pass/Fail rubric title.
description:
type: string
minLength: 20
maxLength: 400
description: A 1-2 sentence Pass condition phrased as a question.
required:
- title
- description
additionalProperties: false
description: The complete custom rubric set for the build. Replaces every existing custom rubric; pass an empty array to clear them.
build_id:
description: Replace the custom rubrics on this build (revision). Defaults to the agent's live build when omitted.
type: string
format: uuid
required:
- rubrics
additionalProperties: false
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
rubrics:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
title:
type: string
description:
type: string
sort_order:
type: number
deleted_at:
nullable: true
type: string
required:
- id
- slug
- title
- description
- sort_order
- deleted_at
additionalProperties: false
platform_rubrics:
type: array
items:
type: object
properties:
key:
type: string
label:
type: string
description:
type: string
cause:
type: string
required:
- key
- label
- description
- cause
additionalProperties: false
required:
- rubrics
- platform_rubrics
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: Replace Eval Rubrics
/v2/agents/{agentId}/eval-rubrics/{rubricId}:
patch:
operationId: updateEvalRubric
tags:
- Agents
description: Edit a single Agent-specific evaluation rubric's title and/or description. The edit produces a NEW rubric (with a new id and slug) so previously scored Runs stay attributed to the original criterion; the response contains the new rubric.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
minLength: 3
maxLength: 80
description: Short, human-readable Pass/Fail rubric title.
description:
type: string
minLength: 20
maxLength: 400
description: A 1-2 sentence Pass condition phrased as a question.
additionalProperties: false
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
- schema:
type: string
format: uuid
in: path
name: rubricId
required: true
description: The custom rubric's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
rubric:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
title:
type: string
description:
type: string
sort_order:
type: number
deleted_at:
nullable: true
type: string
required:
- id
- slug
- title
- description
- sort_order
- deleted_at
additionalProperties: false
required:
- rubric
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: Update Eval Rubric
delete:
operationId: deleteEvalRubric
tags:
- Agents
description: Remove a single Agent-specific evaluation rubric. Future Runs on the build are no longer scored against it.
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
description: The agent's unique identifier (Assignment ID)
- schema:
type: string
format: uuid
in: path
name: rubricId
required: true
description: The custom rubric's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
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
summary: Delete Eval Rubric
/v2/agents/{agent_id}:
get:
operationId: getAgent
tags:
- Agents
description: Get an agent by ID.
parameters:
- schema:
type: string
format: uuid
in: path
name: agent_id
required: true
description: The agent's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
agent:
type: object
properties:
id:
type: string
format: uuid
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
automation_id:
nullable: true
type: string
format: uuid
created_at:
nullable: true
type: string
updated_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
required:
- id
- name
- slack_enabled
- microsoft_teams_enabled
- agentic_memory_enabled
- team_id
- thread_id
- created_at
- updated_at
additionalProperties: false
user_context:
type: object
properties:
pinned_at:
nullable: true
type: string
required:
- pinned_at
additionalProperties: false
required:
- agent
- user_context
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:
applic
# --- truncated at 32 KB (141 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-agents-api-openapi.yml