openapi: 3.0.3 info: title: Duvo Public Agent Folders Skills 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: Skills description: Manage team and system skills (reusable knowledge packs). paths: /v2/skills/system: get: operationId: listSystemSkills tags: - Skills description: List all system skills (skills available to all teams). security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: skills: type: array items: type: object properties: id: type: string format: uuid description: Unique skill identifier name: type: string description: Human-readable skill name description: type: string description: Short summary of what the skill does required: - id - name - description additionalProperties: false description: System skills available to all teams required: - skills 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 '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List System Skills /v2/skills/{skill_id}: delete: operationId: deleteSkill tags: - Skills description: Delete a skill for the current team. parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean description: True if the skill was deleted message: type: string description: Human-readable result message required: - success - message 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 Skill /v2/skills/{skill_id}/download: get: operationId: downloadSkill tags: - Skills description: Download a custom skill as a ZIP archive. Only custom (team-owned) skills can be downloaded. parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: {} '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: Download Skill /v2/skills/{skill_id}/files: get: operationId: listSkillFiles tags: - Skills description: List all files in a skill. parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: files: type: array items: type: object properties: name: type: string description: File name (basename) path: type: string description: Relative path of the file inside the skill size: description: File size in bytes type: number contentType: description: MIME content type of the file type: string updatedAt: description: ISO 8601 timestamp of the last update type: string required: - name - path additionalProperties: false description: Files contained in the skill required: - files 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 Skill Files /v2/skills/{skill_id}/files/{*}: get: operationId: getSkillFileContent tags: - Skills description: Get the content of a file in a skill. parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. - schema: type: string minLength: 1 in: path name: '*' required: true description: Relative path to the file inside the skill, e.g. SKILL.md. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: content: type: string description: UTF-8 decoded contents of the file path: type: string description: Relative path of the file inside the skill contentType: description: MIME content type inferred from the file extension type: string required: - content - path 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 Skill File Content put: operationId: updateSkillFile tags: - Skills description: Update the content of a file in a skill. Only team skills can be edited. requestBody: required: true content: application/json: schema: type: object properties: content: type: string description: New UTF-8 text content for the file. required: - content parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. - schema: type: string minLength: 1 in: path name: '*' required: true description: Relative path to the file inside the skill, e.g. SKILL.md. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean description: True if the file was updated message: type: string description: Human-readable result message skill: description: Updated skill metadata, present only when SKILL.md was edited type: object properties: id: type: string description: Unique skill identifier name: type: string description: Updated skill name parsed from SKILL.md description: type: string description: Updated skill description parsed from SKILL.md required: - id - name - description additionalProperties: false required: - success - message additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false summary: Update Skill File /v2/skills/{skill_id}/assignments: get: operationId: listSkillAssignments tags: - Skills description: List the agents in the current team whose live build references the given skill. Used to warn users that editing a skill will affect every agent that uses it. parameters: - schema: type: string format: uuid in: path name: skill_id required: true description: Skill ID. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: assignments: type: array items: type: object properties: id: type: string description: Unique assignment (agent) identifier name: type: string description: Human-readable assignment name required: - id - name additionalProperties: false description: Agents in the current team whose live build uses the skill total: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of assignments referencing the skill required: - assignments - total 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 Skill Assignments /v2/teams/{teamId}/skills: get: operationId: listSkills tags: - Skills description: List all skills for the current team, including system skills. security: - bearerAuth: [] parameters: - schema: type: string in: path name: teamId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: skills: type: array items: type: object properties: id: type: string format: uuid description: Unique skill identifier name: type: string description: Human-readable skill name description: type: string description: Short summary of what the skill does team_id: nullable: true description: ID of the team that owns the skill, or null for system skills type: string format: uuid updated_at: type: string description: ISO timestamp of the last update updated_by_user_id: nullable: true description: User ID of the last person who updated the skill type: string updated_by_user_name: nullable: true description: Display name of the last person who updated the skill (falls back to email) type: string source: nullable: true description: 'How the skill was created: ''browser'' or ''computer_use'' if generated from a recording, otherwise null (created/uploaded)' type: string enum: - browser - computer_use computer_use_backend: nullable: true description: 'For computer-use skills, the backend it was recorded on: ''rdp'' (Remote Desktop) or ''sandbox'' (Duvo sandbox); null for other skills. Used to warn about backend mismatches at build time.' type: string enum: - rdp - sandbox required: - id - name - description - team_id - updated_at - updated_by_user_id - updated_by_user_name - source - computer_use_backend additionalProperties: false description: Skills available to the current team (team and system skills) required: - skills 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 '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Skills post: operationId: createSkill tags: - Skills description: Create or update a skill from a JSON body. The server constructs SKILL.md from the provided fields and stores it. If a skill with the same name already exists in the team, it is updated. requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: Skill name. 1-64 lowercase alphanumeric chars and hyphens; no leading/trailing or consecutive hyphens. description: type: string minLength: 1 maxLength: 1024 description: 1-1024 chars describing what the skill does and when to invoke it. content: type: string description: Markdown body of SKILL.md without YAML frontmatter. The server prepends the frontmatter from the other fields. license: description: 'Optional: license name or reference to a bundled license file.' type: string compatibility: description: 'Optional: 1-500 chars describing environment requirements.' type: string maxLength: 500 metadata: description: 'Optional: arbitrary key-value metadata.' type: object additionalProperties: {} allowed-tools: description: 'Optional (experimental): space-delimited list of pre-approved tools.' type: string required: - name - description - content security: - bearerAuth: [] parameters: - schema: type: string in: path name: teamId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: skill: type: object properties: id: type: string format: uuid description: Unique skill identifier name: type: string description: Human-readable skill name description: type: string description: Short summary of what the skill does team_id: type: string format: uuid description: ID of the team that owns the skill required: - id - name - description - team_id additionalProperties: false description: The created or updated skill required: - skill additionalProperties: false '201': description: Default Response content: application/json: schema: type: object properties: skill: type: object properties: id: type: string format: uuid description: Unique skill identifier name: type: string description: Human-readable skill name description: type: string description: Short summary of what the skill does team_id: type: string format: uuid description: ID of the team that owns the skill required: - id - name - description - team_id additionalProperties: false description: The created or updated skill required: - skill additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string description: Short error code message: description: Human-readable error message type: string validationErrors: description: Per-field validation errors, present on frontmatter validation failure type: array items: type: object properties: field: type: string description: Name of the invalid field message: type: string description: Validation error message for the field required: - field - message additionalProperties: false required: - error additionalProperties: false summary: Create Skill /v2/teams/{teamId}/skills/upload: post: operationId: uploadSkill tags: - Skills description: Create or update a skill by uploading a SKILL.md file or a ZIP archive containing SKILL.md at the root. If a skill with the same name exists in the team, it will be updated. security: - bearerAuth: [] parameters: - schema: type: string in: path name: teamId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: skill: type: object properties: id: type: string format: uuid name: type: string description: type: string team_id: type: string format: uuid required: - id - name - description - team_id additionalProperties: false required: - skill additionalProperties: false '201': description: Default Response content: application/json: schema: type: object properties: skill: type: object properties: id: type: string format: uuid name: type: string description: type: string team_id: type: string format: uuid required: - id - name - description - team_id additionalProperties: false required: - skill additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string validationErrors: type: array items: type: object properties: field: type: string message: type: string required: - field - message additionalProperties: false required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string validationErrors: type: array items: type: object properties: field: type: string message: type: string required: - field - message additionalProperties: false required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string validationErrors: type: array items: type: object properties: field: type: string message: type: string required: - field - message additionalProperties: false required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string validationErrors: type: array items: type: object properties: field: type: string message: type: string required: - field - message additionalProperties: false required: - error additionalProperties: false summary: Upload Skill components: securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication. Get your API key from the Duvo dashboard.