openapi: 3.2.0
info:
  title: Pipeshub Skills API
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
  description: 'Operations tagged Skills across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Skills
  description: 'Beta: Skills (SKILL.md packages) that agents load on demand — CRUD, versioning,

    resources, import (npm/URL/upload), and learning-loop candidate review. Gated by

    the ENABLE_SKILLS platform feature flag; disabled orgs get 403 on every route.'
paths:
  /skills:
    get:
      tags:
      - Skills
      summary: List skills
      description: 'List skills visible to the caller (their own custom skills plus org-wide

        builtins). Also seeds the org''s builtin skill catalog on first call if it

        hasn''t been seeded yet, so a fresh org sees builtins in the UI before its

        first chat.'
      operationId: listSkills
      security:
      - bearerAuth: []
      parameters:
      - name: category
        in: query
        schema:
          type: string
      - name: subcategory
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - deprecated
          - candidate
          - disabled
      - name: source
        in: query
        schema:
          type: string
          enum:
          - builtin
          - manual
          - imported
          - learned
      - name: tag
        in: query
        schema:
          type: string
      - name: q
        in: query
        schema:
          type: string
        description: Free-text search across name/description/tags.
      responses:
        '200':
          description: Skills retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  skills:
                    type: array
                    items:
                      $ref: '#/components/schemas/SkillMetadata'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization (ENABLE_SKILLS is off)
    post:
      tags:
      - Skills
      summary: Create a custom skill
      description: 'Creates a new custom skill from structured form fields. Rejects (409) a

        name that collides with a builtin pack name (e.g. `pdf`), so a custom

        skill can never shadow a real builtin before it''s seeded.'
      operationId: createSkill
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SkillWriteRequest'
              - type: object
                required:
                - name
      responses:
        '201':
          description: Skill created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '400':
          description: Invalid payload, or the rendered SKILL.md failed validation
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '409':
          description: A skill with this name already exists, or the name is reserved for a builtin pack
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/categories:
    get:
      tags:
      - Skills
      summary: Get skill categories and tags
      operationId: getSkillCategories
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Categories and tags retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      type: string
                  tags:
                    type: array
                    items:
                      type: string
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/search:
    get:
      tags:
      - Skills
      summary: Search skills
      description: Semantic + keyword search over the skill catalog, ranked by relevance.
      operationId: searchSkills
      security:
      - bearerAuth: []
      parameters:
      - name: q
        in: query
        schema:
          type: string
          default: ''
      - name: category
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        skill:
                          $ref: '#/components/schemas/SkillMetadata'
                        relevance:
                          type: number
                        matchReason:
                          type: string
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/candidates/pending:
    get:
      tags:
      - Skills
      summary: List pending learning-loop skill candidates
      description: Skill candidates surfaced by the learning loop, awaiting admin/owner review before promotion into the catalog.
      operationId: getPendingSkillCandidates
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Pending candidates retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidates:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/candidates/{candidateId}/approve:
    post:
      tags:
      - Skills
      summary: Approve a skill candidate
      description: Promotes a learning-loop candidate into a real, active skill.
      operationId: approveSkillCandidate
      security:
      - bearerAuth: []
      parameters:
      - name: candidateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Candidate approved and promoted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Candidate not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/candidates/{candidateId}/reject:
    post:
      tags:
      - Skills
      summary: Reject a skill candidate
      operationId: rejectSkillCandidate
      security:
      - bearerAuth: []
      parameters:
      - name: candidateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Candidate rejected
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/import/npm/preview:
    post:
      tags:
      - Skills
      summary: Preview an npm-sourced skill import
      description: 'Stateless preview — resolves and downloads the npm package but persists

        nothing. Follow with `POST /skills/import/finalize` using the returned

        `content`/`resources` to actually create the skill.'
      operationId: previewNpmSkillImport
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillNpmImportRequest'
      responses:
        '200':
          description: Preview generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImportPreview'
        '400':
          description: Invalid npm command/name, or the package could not be parsed as a skill
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/import/url/preview:
    post:
      tags:
      - Skills
      summary: Preview a URL-sourced skill import
      description: 'Downloads via an SSRF-safe fetcher with size limits and zip-slip

        protection. Stateless — nothing is persisted until finalize.'
      operationId: previewUrlSkillImport
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillUrlImportRequest'
      responses:
        '200':
          description: Preview generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImportPreview'
        '400':
          description: Invalid URL, or the archive could not be parsed as a skill
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/import/upload/preview:
    post:
      tags:
      - Skills
      summary: Preview an uploaded skill archive
      description: 'Accepts a zip archive up to 25MB (mirrors the npm/URL archive size

        ceiling). Stateless — nothing is persisted until finalize.'
      operationId: previewUploadSkillImport
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Preview generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImportPreview'
        '400':
          description: No file uploaded, or the archive could not be parsed as a skill
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/import/finalize:
    post:
      tags:
      - Skills
      summary: Finalize a previewed skill import
      description: 'Persists a preview from any of the three sources (npm/URL/upload) —

        the preview step already normalized all three into the same

        `content`/`resources` shape. Rejects (409) a name reserved for a

        builtin pack.'
      operationId: finalizeSkillImport
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillFinalizeImportRequest'
      responses:
        '201':
          description: Skill created from the imported content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '400':
          description: Imported SKILL.md is missing a name, or failed validation
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '409':
          description: A skill with this name already exists, or the name is reserved for a builtin pack
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}:
    get:
      tags:
      - Skills
      summary: Get a skill
      description: Returns the full skill — metadata, editable body, and bundled resource listing.
      operationId: getSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Skill retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
    put:
      tags:
      - Skills
      summary: Update a skill
      description: Full update of a skill's content and metadata from structured form fields. Builtin skills can only be edited by the seeding identity — a non-owner attempt surfaces as 404/409.
      operationId: updateSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillWriteRequest'
      responses:
        '200':
          description: Skill updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '400':
          description: Invalid payload, or the rendered SKILL.md failed validation
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
        '409':
          description: Update conflicts with the skill's current state
    delete:
      tags:
      - Skills
      summary: Delete a skill (safe delete)
      description: 'Refuses to delete a skill that''s in use (409, with structured

        `usedByAgents`/`requiredBySkills` — see `SkillUsage`) unless

        `detach=true`. A skill another skill `requires` can NEVER be

        force-deleted — deprecate it instead so dependents still resolve.

        `detach=true` unassigns the skill from any agents (removing the

        `agentHasSkill` edges) before deleting; call `GET /skills/{name}/usage`

        first to show the user which agents will be affected.'
      operationId: deleteSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: detach
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Skill deleted
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
        '409':
          description: Skill is in use — response body is a SkillUsage-shaped object plus a message
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SkillUsage'
                - type: object
                  properties:
                    message:
                      type: string
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/export:
    get:
      tags:
      - Skills
      summary: Export a skill as SKILL.md
      description: Returns the rendered SKILL.md as a downloadable text/markdown file.
      operationId: exportSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: SKILL.md content
          content:
            text/markdown:
              schema:
                type: string
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/body:
    patch:
      tags:
      - Skills
      summary: Patch a skill's body with an exact string replacement
      description: Fails 400 if `old_string` doesn't exist, or exists more than once, in the current body.
      operationId: patchSkillBody
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillPatchBodyRequest'
      responses:
        '200':
          description: Body patched
        '400':
          description: old_string not found exactly once, or the skill doesn't exist
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/deprecate:
    post:
      tags:
      - Skills
      summary: Deprecate a skill
      description: Marks a skill deprecated (optionally pointing to a replacement) without deleting it — dependents that `requires` it keep resolving.
      operationId: deprecateSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillDeprecateRequest'
      responses:
        '200':
          description: Skill deprecated
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/disable:
    post:
      tags:
      - Skills
      summary: Disable a skill
      description: 'Reversible mute: the skill stays in the library but is hidden from

        every agent-facing catalog/search surface and can no longer be

        loaded or newly assigned. Unlike deprecate, this is not a lifecycle

        judgment (no reason, no replacement) and is undone with `POST

        /skills/{name}/enable`.


        Custom skills: only the creator can disable (a non-owner gets 404,

        matching GET). Builtin skills: only an organization admin; members

        get 403. Content edits of builtins remain 403.'
      operationId: disableSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Skill disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization, or a non-admin tried to disable a builtin skill
        '404':
          description: Skill not found
        '409':
          description: Skill is not currently active (e.g. already disabled, or deprecated)
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/enable:
    post:
      tags:
      - Skills
      summary: Re-enable a disabled skill
      description: 'Reverses `POST /skills/{name}/disable` — restores catalog/search

        visibility and loadability. Only valid from `disabled`; does not

        undeprecate a deprecated skill. Same authorization as disable:

        creator for custom skills, organization admin for builtins.'
      operationId: enableSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Skill enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization, or a non-admin tried to enable a builtin skill
        '404':
          description: Skill not found
        '409':
          description: Skill is not currently disabled (e.g. already active, or deprecated)
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/usage:
    get:
      tags:
      - Skills
      summary: Get a skill's usage
      description: Referential-integrity snapshot (agents it's assigned to, skills that require it) — call before a safe delete to show the user what will be affected.
      operationId: getSkillUsage
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Usage retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillUsage'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/versions:
    get:
      tags:
      - Skills
      summary: List a skill's version history
      operationId: listSkillVersions
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Versions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/SkillVersionSummary'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/versions/{version}:
    get:
      tags:
      - Skills
      summary: Get a specific skill version
      operationId: getSkillVersion
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Version retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill or version not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/rollback:
    post:
      tags:
      - Skills
      summary: Roll back a skill to a prior version
      operationId: rollbackSkill
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillRollbackRequest'
      responses:
        '200':
          description: Skill rolled back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillMetadata'
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill or version not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /skills/{name}/resource:
    get:
      tags:
      - Skills
      summary: Get a bundled resource
      description: Returns the raw text content of a bundled resource file (e.g. `scripts/run.py`).
      operationId: getSkillResource
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: path
        in: query
        required: true
        schema:
          type: string
        description: Path relative to the skill's own root.
      responses:
        '200':
          description: Resource content
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill or resource not found
    put:
      tags:
      - Skills
      summary: Write a bundled resource
      description: 'Creates or overwrites a text resource file under the skill''s directory.

        Rejects (400) path traversal, absolute paths, `SKILL.md`, and payloads

        that exceed the per-file/per-skill byte budget. Binary resources are

        not yet supported (deferred to a blob-storage follow-up).'
      operationId: writeSkillResource
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkillResourceWriteRequest'
      responses:
        '200':
          description: Resource written
        '400':
          description: Invalid path, or resource exceeds the byte budget
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill not found
    delete:
      tags:
      - Skills
      summary: Remove a bundled resource
      operationId: removeSkillResource
      security:
      - bearerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: path
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource removed
        '401':
          description: Unauthorized
        '403':
          description: Skills are disabled for this organization
        '404':
          description: Skill or resource not found
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
components:
  schemas:
    SkillNpmImportRequest:
      type: object
      required:
      - command_or_name
      properties:
        command_or_name:
          type: string
          minLength: 1
          example: npm install @anthropic/skill-pdf
    SkillImportPreview:
      type: object
      description: Stateless preview of an npm/URL/upload import source — nothing is persisted until `POST /skills/import/finalize`.
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: string
        content:
          type: string
          description: Full SKILL.md text extracted from the archive/package.
        resources:
          type: object
          additionalProperties:
            type: string
        warnings:
          type: array
          items:
            type: string
        skippedBinaryResources:
          type: array
          items:
            type: string
          description: Resource paths that were skipped because they are binary (text-only resources are supported today).
        sourceLabel:
          type: string
          example: npm:@anthropic/skill-pdf
    SkillUsage:
      type: object
      description: Referential-integrity snapshot used to gate `DELETE /skills/{name}`.
      properties:
        usedByAgents:
          type: array
          items:
            $ref: '#/components/schemas/SkillUsageReference'
          description: Agents this skill is currently assigned to via Agent Builder.
        requiredBySkills:
          type: array
          items:
            type: string
          description: Other skill names whose frontmatter declares `requires` on this one — these can NEVER be force-deleted, only deprecated.
    Skill:
      description: Full skill — metadata plus editable body and bundled resource listing.
      allOf:
      - $ref: '#/components/schemas/SkillMetadata'
      - type: object
        properties:
          body:
            type: string
            description: Markdown body (everything after the YAML frontmatter) — Tiptap-edited in the UI.
          resources:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
            description: Bundled resource paths grouped by first path segment (e.g. `scripts`, `references`, `assets`, or `files` for root-level files).
    SkillFinalizeImportRequest:
      type: object
      description: Persists exactly what a prior `preview_*` call returned — the client round-trips `content`/`resources` verbatim.
      required:
      - content
      properties:
        content:
          type: string
          minLength: 1
          description: Full SKILL.md text (with YAML frontmatter) as returned by the preview step.
        resources:
          type: object
          additionalProperties:
            type: string
        category:
          type:
          - string
          - 'null'
        subcategory:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
          description: Optional kebab-case name to persist as. Rewrites SKILL.md frontmatter `name` so an import can avoid a reserved builtin.
    SkillWriteRequest:
      type: object
      description: 'Structured create/update payload. The backend renders this into a full,

        spec-compliant SKILL.md string server-side — clients never hand-assemble

        YAML frontmatter.

        '
      required:
      - description
      - body
      properties:
        name:
          type: string
          description: Required on create; ignored on update (the `{name}` path param is authoritative).
        description:
          type: string
          minLength: 1
        body:
          type: string
          minLength: 1
        category:
          type:
          - string
          - 'null'
        subcategory:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        license:
          type:
          - string
          - 'null'
        compatibility:
          type:
          - string
          - 'null'
        allowed_tools:
          type:
          - array
          - 'null'
          items:
            type: string
        related:
          type: array
          items:
            type: string
        requires:
          type: array
          items:
            type: string
        concepts:
          type: array
          items:
            type: string
    SkillPatchBodyRequest:
      type: object
      description: Exact-match string replacement against the skill's current body — fails 400 if `old_string` isn't found exactly once.
      required:
      - old_string
      - new_string
      properties:
        old_string:
          type: string
        new_string:
          type: string
    SkillRollbackRequest:
      type: object
      required:
      - version
      properties:
        version:
          type: string
          minLength: 1
    SkillResourceWriteRequest:
      type: object
      required:
      - path
      - content
      properties:
        path:
          type: string
          minLength: 1
          description: Path relative to the skill's own root (e.g. `scripts/run.py`). Traversal (`..`), absolute paths, and `SKILL.md` are rejected with 400.
        content:
          type: string
          description: Text content only — binary resources are not yet supported (deferred to a blob-storage follow-up).
    SkillMetadata:
      type: object
      description: 'Skill metadata (SKILL.md YAML frontmatter, agentskills.io-compatible, plus

        PipesHub lifecycle fields nested under `metadata["agent-loop"]` on the wire

        format — flattened here for the REST response). Returned by list/search/

        create/update/deprecate/rollback; `GET /skills/{name}` returns this shape

        plus `body`/`resources` (see Skill).

        '
      properties:
        name:
          type: string
          description: Unique skill identifier (kebab-case, matches `^[a-z0-9]+(-[a-z0-9]+)*$`, max 64 chars).
          example: deploy-runbook
        description:
          type: string
          description: One-line summary shown in skill_search/skills_list (max 1024 chars).
        version:
          type: string
          example: 1.0.0
        category:
          type:
          - string
          - 'null'
        subcategory:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - deprecated
          - candidate
          - disabled
        source:
          type: string
          enum:
          - builtin
          - manual
          - imported
          - learned
          description: '`builtin` skills are seeded by `BuiltinSkillSeeder` and read-only for end users.'
        license:
          type:
          - string
          - 'null'
        compatibility:
          type:
          - string
          - 'null'
        allowedTools:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Optional allowlist from the `allowed-tools` frontmatter key (metadata only today — not yet enforced at the tool registry).
        related:
          type: array
          items:
            type: string
        requires:
          type: array
          items:
            type: string
          description: Other skill names this skill's body depends on — staged transitively alongside it into the coding sandbox.
        concepts:
          type: array
          items:
            type: string
        deprecatedReason:
          type:
          - string
          - 'null'
        replacedBy:
          type:
          - string
          - 'null'
        createdAt:
          oneOf:
          - type:
            - string
            - 'null'
          - type: integer
        updatedAt:
          oneOf:
          - type:
            - string
            - 'null'
          - type: integer
        packName:
          type:
          - string
          - 'null'
          description: Builtin pack name this skill was seeded from, if `source == builtin`.
        packVersion:
          type:
          - string
          - 'null'
    SkillDeprecateRequest:
      type: object
      required:
      - reason
      properties:
        reason:
          type: string
          minLength: 1
        replaced_by:
          type:
          - string
          - 'null'
    SkillVersionSummary:
      type: object
      properties:
        version:
          type: string
        updatedBy:
          type:
          - string
          - 'null'
        createdAt:
          oneOf:
          - type:
            - string
            - 'null'
          - type: integer
        summary:
          type:
          - string
          - 'null'
    SkillUsageReference:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    SkillUrlImportRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          minLength: 1
          example: https://example.com/my-skill.zip
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
x-refined-from:
- pipeshub-openapi.yaml
- pipeshub-openapi.yml