duvo.ai Skills API

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
     

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-skills-api-openapi.yml