OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders 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: Agent Folders
description: Organize agents into folders
paths:
/v2/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
parameters:
- schema:
type: string
format: uuid
in: path
name: folder_id
required: true
description: The folder's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
folder:
type: object
properties:
id:
type: string
format: uuid
description: Unique folder identifier
name:
type: string
description: Human-readable folder name
team_id:
type: string
format: uuid
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
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
'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: Update Agent Folder
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
in: path
name: folder_id
required: true
description: The folder's unique identifier
security:
- bearerAuth: []
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
'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: Delete Agent Folder
/v2/teams/{teamId}/agent-folders:
get:
operationId: listAgentFolders
tags:
- Agent Folders
description: List all agent folders for the authenticated team.
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
folders:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Unique folder identifier
name:
type: string
description: Folder display name
team_id:
type: string
format: uuid
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
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
summary: List 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
required:
- name
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
folder:
type: object
properties:
id:
type: string
format: uuid
description: Unique folder identifier
name:
type: string
description: Human-readable folder name
team_id:
type: string
format: uuid
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
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
'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 Agent Folder
/v2/teams/{teamId}/agent-folders/move-agents:
post:
operationId: moveAgentsToFolder
tags:
- Agent Folders
description: Move one or more agents (assignments) into a folder, or to the root level.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
agent_ids:
minItems: 1
type: array
items:
type: string
format: uuid
description: IDs of the agents (assignments) to move. Must be unique.
folder_id:
nullable: true
description: Destination folder ID. Pass null to move the agents to the root level.
type: string
format: uuid
required:
- agent_ids
- folder_id
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Always true on success
moved_count:
type: number
description: Number of agents that were moved
required:
- success
- moved_count
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
'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: Move Agents To Folder
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your API key from the Duvo dashboard.