openapi: 3.0.0
info:
  title: Dust Skills API
  version: 1.0.2
  description: List and import skill bundles into a Dust workspace.
  contact:
    name: Dust Support
    url: https://docs.dust.tt
  license:
    name: MIT
    url: https://github.com/dust-tt/dust/blob/main/LICENSE
servers:
- url: https://dust.tt
  description: Dust.tt API (us-central1)
- url: https://eu.dust.tt
  description: Dust.tt API (europe-west1)
tags:
- name: Skills
  description: Skills
paths:
  /api/v1/w/{wId}/skills:
    get:
      summary: List Skills
      description: Retrieves the custom skills in the workspace. Active skills are returned by default.
      tags:
      - Skills
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: Unique string identifier for the workspace
        schema:
          type: string
      - in: query
        name: status
        required: false
        description: Filter skills by status. Defaults to active.
        schema:
          type: string
          enum:
          - active
          - archived
          - suggested
      responses:
        '200':
          description: Skills available in the workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  skills:
                    type: array
                    items:
                      $ref: '#/components/schemas/Skill'
        '400':
          description: Bad Request. Missing or invalid parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '404':
          description: Workspace not found.
        '405':
          description: Method not supported.
    post:
      summary: Import Skills from Uploaded Files
      description: Imports skills from uploaded files or ZIP archives into the workspace.
      tags:
      - Skills
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: Unique string identifier for the workspace
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Skill files or ZIP archives to import.
                names:
                  type: array
                  items:
                    type: string
                  description: Optional skill names to import from the uploaded files.
                onConflict:
                  type: string
                  enum:
                  - error
                  - skip
                  - override
                  description: Conflict handling strategy. Defaults to error.
      responses:
        '200':
          description: Skills import result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported:
                    type: array
                    items:
                      $ref: '#/components/schemas/Skill'
                  updated:
                    type: array
                    items:
                      $ref: '#/components/schemas/Skill'
                  skipped:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        message:
                          type: string
        '400':
          description: Bad Request. Missing or invalid uploaded files.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '404':
          description: Workspace not found.
        '405':
          description: Method not supported.
components:
  schemas:
    MCPServerView:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the MCP server view
          example: 123
        sId:
          type: string
          description: Unique string identifier for the MCP server view
          example: mcp_sv_abc123
        name:
          type: string
          nullable: true
          description: Custom name for the MCP server view (null if not set)
          example: My Custom MCP Server
        description:
          type: string
          nullable: true
          description: Custom description for the MCP server view (null if not set)
          example: This MCP server handles customer data operations
        createdAt:
          type: number
          description: Unix timestamp of when the MCP server view was created
          example: 1625097600
        updatedAt:
          type: number
          description: Unix timestamp of when the MCP server view was last updated
          example: 1625184000
        spaceId:
          type: string
          description: ID of the space containing the MCP server view
          example: spc_xyz789
        serverType:
          type: string
          enum:
          - remote
          - internal
          description: Type of the MCP server
          example: remote
        server:
          type: object
          properties:
            sId:
              type: string
              description: Unique string identifier for the MCP server
              example: mcp_srv_def456
            name:
              type: string
              description: Name of the MCP server
              example: Customer Data Server
            version:
              type: string
              description: Version of the MCP server
              example: 1.0.0
            description:
              type: string
              description: Description of the MCP server
              example: Handles customer data operations and queries
            icon:
              type: string
              description: Icon identifier for the MCP server
              example: database
            authorization:
              type: object
              nullable: true
              properties:
                provider:
                  type: string
                  description: OAuth provider for authorization
                  example: github
                supported_use_cases:
                  type: array
                  items:
                    type: string
                    enum:
                    - platform_actions
                    - personal_actions
                  description: Supported use cases for the authorization
                  example:
                  - platform_actions
                scope:
                  type: string
                  description: OAuth scope required
                  example: repo:read
            tools:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the tool
                    example: query_customers
                  description:
                    type: string
                    description: Description of what the tool does
                    example: Query customer database for information
                  inputSchema:
                    type: object
                    description: JSON Schema for the tool's input parameters
                    example:
                      type: object
                      properties:
                        customerId:
                          type: string
            availability:
              type: string
              description: Availability status of the MCP server
              example: production
            allowMultipleInstances:
              type: boolean
              description: Whether multiple instances of this server can be created
              example: false
            documentationUrl:
              type: string
              nullable: true
              description: URL to the server's documentation
              example: https://docs.example.com/mcp-server
        oAuthUseCase:
          type: string
          nullable: true
          enum:
          - platform_actions
          - personal_actions
          description: OAuth use case for the MCP server view
          example: platform_actions
        editedByUser:
          type: object
          nullable: true
          description: Information about the user who last edited the MCP server view
          properties:
            editedAt:
              type: number
              nullable: true
              description: Unix timestamp of when the edit occurred
              example: 1625184000
            fullName:
              type: string
              nullable: true
              description: Full name of the editor
              example: John Doe
            imageUrl:
              type: string
              nullable: true
              description: Profile image URL of the editor
              example: https://example.com/profile/johndoe.jpg
    Skill:
      type: object
      properties:
        sId:
          type: string
          description: Unique string identifier for the skill
          example: skill_abc123
        createdAt:
          type: number
          nullable: true
          description: Timestamp of when the skill was created
        updatedAt:
          type: number
          nullable: true
          description: Timestamp of when the skill was last updated
        editedBy:
          type: integer
          nullable: true
          description: Numeric identifier of the last editor
        status:
          type: string
          enum:
          - active
          - archived
          - suggested
          description: Current status of the skill
          example: active
        name:
          type: string
          description: Name of the skill
          example: Customer Support
        agentFacingDescription:
          type: string
          description: Description shown to agents when selecting or using the skill
          example: Use this skill to answer customer support questions.
        userFacingDescription:
          type: string
          description: Description shown to workspace users
          example: Answers support questions with the right workspace context.
        icon:
          type: string
          nullable: true
          description: Icon identifier for the skill
          example: ActionRobotIcon
        source:
          type: string
          nullable: true
          enum:
          - web_app
          - github
          - api
          - local_file
          description: Source used to create or import the skill
        sourceMetadata:
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/SkillSourceMetadata'
        reinforcement:
          type: string
          enum:
          - auto
          - 'on'
          - 'off'
          description: Reinforcement setting for the skill
        lastReinforcementAnalysisAt:
          type: string
          nullable: true
          description: Timestamp of the last reinforcement analysis, when available
        requestedSpaceIds:
          type: array
          items:
            type: string
          description: Space identifiers the skill needs access to
        fileAttachments:
          type: array
          items:
            type: object
            properties:
              fileId:
                type: string
                description: Unique string identifier for the attached file
              fileName:
                type: string
                description: Name of the attached file
        canWrite:
          type: boolean
          description: Whether the authenticated actor can edit the skill
        isExtendable:
          type: boolean
          description: Whether this skill can be extended by another skill
        isDefault:
          type: boolean
          description: Whether this skill is enabled by default
        extendedSkillId:
          type: string
          nullable: true
          description: Identifier of the extended skill, when applicable
        instructions:
          type: string
          nullable: true
          description: Instructions used by the agent when running the skill
        instructionsHtml:
          type: string
          nullable: true
          description: HTML representation of the skill instructions
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPServerView'
    SkillSourceMetadata:
      type: object
      properties:
        repoUrl:
          type: string
          description: URL of the source repository, when applicable
          example: https://github.com/dust-tt/skills
        filePath:
          type: string
          description: Path to the source skill file
          example: support/SKILL.md
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Your DUST API key is a Bearer token.