openapi: 3.2.0
info:
  title: AutoGPT Agent Server Skills API
  summary: AutoGPT Agent Server
  description: This server is used to execute agents that are created by the AutoGPT system.
  version: '0.1'
tags:
- name: Skills
paths:
  /api/skills:
    get:
      tags:
      - Skills
      summary: List user-distilled copilot skills
      description: 'Return user-stored skills for the current user.


        Reuses :func:`backend.copilot.tools.skills.list_user_skills` so the

        library UI sees the exact same set the copilot ````

        block surfaces, minus the built-in defaults (which are read-only and

        handled separately by the copilot runtime).'
      operationId: listCopilotSkills
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CopilotSkillInfo'
                type: array
                title: Response Listcopilotskills
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
      security:
      - HTTPBearerJWT: []
    post:
      tags:
      - Skills
      summary: Upload a copilot skill from a SKILL.md file
      description: 'Create a user-distilled skill from an uploaded ``SKILL.md`` file.


        Parses the canonical frontmatter + body, then reuses

        :func:`backend.copilot.tools.skills.store_user_skill` so an uploaded skill

        is validated, capped, and persisted exactly like one the copilot distils

        via ``store_skill``. Malformed files return 400, the per-user cap returns

        409, and an existing slug is overwritten (upsert).'
      operationId: uploadCopilotSkill
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadCopilotSkillRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopilotSkillInfo'
        '400':
          description: Malformed SKILL.md or validation error
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '409':
          description: Per-user skill limit reached
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearerJWT: []
  /api/skills/{name}:
    delete:
      tags:
      - Skills
      summary: Delete a user-distilled copilot skill
      description: 'Delete a user-distilled skill by slug.


        Built-in defaults are not user-deletable — attempting to delete one

        returns 400. Missing skills return 404 so the UI can reconcile a

        stale list.'
      operationId: deleteCopilotSkill
      security:
      - HTTPBearerJWT: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          description: Slug of the skill to delete
          title: Name
        description: Slug of the skill to delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Deletecopilotskill
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Skills
      summary: Read a single copilot skill with its full SKILL.md body
      description: 'Return full SKILL.md content (name, description, triggers, body)

        for the library UI''s expand-to-view dialog.


        Built-in default skills are returned with ``is_default=True`` so the

        UI can hide destructive affordances; missing user skills return 404.'
      operationId: readCopilotSkill
      security:
      - HTTPBearerJWT: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          description: Slug of the skill to read
          title: Name
        description: Slug of the skill to read
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopilotSkillDetail'
        '401':
          $ref: '#/components/responses/HTTP401NotAuthenticatedError'
        '404':
          description: Skill not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  responses:
    HTTP401NotAuthenticatedError:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CopilotSkillDetail:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        triggers:
          items:
            type: string
          type: array
          title: Triggers
          default: []
        body:
          type: string
          title: Body
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        is_default:
          type: boolean
          title: Is Default
          default: false
        sibling_files:
          items:
            type: string
          type: array
          title: Sibling Files
          default: []
      type: object
      required:
      - name
      - description
      - body
      title: CopilotSkillDetail
      description: Full SKILL.md content surfaced to the library expand-to-view UI.
    UploadCopilotSkillRequest:
      properties:
        content:
          type: string
          title: Content
      type: object
      required:
      - content
      title: UploadCopilotSkillRequest
      description: 'Body for the library UI''s "upload skill" action.


        Carries the raw ``SKILL.md`` text (YAML frontmatter + markdown body) the

        user picked from disk; the server parses + validates it so the upload and

        the copilot''s ``store_skill`` tool share one source of truth.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CopilotSkillInfo:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        triggers:
          items:
            type: string
          type: array
          title: Triggers
          default: []
      type: object
      required:
      - name
      - description
      title: CopilotSkillInfo
      description: 'User-distilled copilot skill metadata for the library UI.


        Defaults (built-in agent-building / MCP-tool guides) are intentionally

        excluded — they cannot be edited or deleted, so surfacing them in the

        user-facing list would add noise without affordances.'
  securitySchemes:
    APIKeyAuthenticator-X-Postmark-Webhook-Token:
      type: apiKey
      in: header
      name: X-Postmark-Webhook-Token
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBearerJWT:
      type: http
      scheme: bearer
      bearerFormat: jwt