openapi: 3.1.0
info:
  title: 'Skill Registry API'
  description: 'The registry for AI agent skills (SKILL.md bundles) — browse them, download them as a zip, or install them via the revenexx CLI into any supported agent; sourced from connected Git repositories. Agent-agnostic, not Claude-only.'
  version: 1.0.0
servers:
  - url: 'https://skills.revenexx.ai'
tags:
  - name: Skills
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: "Authenticate with a Zitadel-issued OIDC JWT as a bearer token. The public plane (`/v1`) requires any role in the Revenue Cloud project (read access). A skill's visibility is resolved against the caller's Zitadel organization."
security:
  -
    default: []
paths:
  /api/v1/skills:
    get:
      summary: 'List skills visible to the calling organisation.'
      operationId: listSkillsVisibleToTheCallingOrganisation
      description: "Optional `?q=` filters by name/title/description/tags. Visibility is scoped to\nthe caller's Zitadel organization: public skills are returned to everyone,\nprivate skills only to the owning organization."
      parameters:
        -
          in: query
          name: q
          description: 'Optional search over name/title/description/tags.'
          required: false
          schema:
            type: string
            description: 'Optional search over name/title/description/tags.'
            examples:
              - invoice
        -
          in: query
          name: category
          description: 'Optional exact category filter.'
          required: false
          schema:
            type: string
            description: 'Optional exact category filter.'
            examples:
              - finance
        -
          in: query
          name: tags
          description: 'Optional comma-separated tag filter; a skill matching any listed tag is returned.'
          required: false
          schema:
            type: string
            description: 'Optional comma-separated tag filter; a skill matching any listed tag is returned.'
            examples:
              - 'erp,invoice'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                          examples:
                            - revenexx
                        name:
                          type: string
                          examples:
                            - invoice-sync
                        slug:
                          type: string
                          examples:
                            - revenexx/invoice-sync
                        title:
                          type: string
                          examples:
                            - 'Invoice Sync'
                        description:
                          type: string
                          examples:
                            - 'Sync invoices between Business Central and the data warehouse.'
                        visibility:
                          type: string
                          examples:
                            - public
                        category:
                          type: string
                          examples:
                            - finance
                        tags:
                          type: array
                          items:
                            type: string
                          examples:
                            -
                              - invoice
                              - erp
                        latest_version:
                          type: string
                          examples:
                            - 1.2.0
                        latest_download_url:
                          type: string
                          examples:
                            - 'https://skills.rvnxx.test/api/v1/skills/revenexx/skills-catalog/invoice-sync/versions/1.2.0/download'
                    examples:
                      -
                        -
                          vendor: revenexx
                          name: invoice-sync
                          slug: revenexx/invoice-sync
                          title: 'Invoice Sync'
                          description: 'Sync invoices between Business Central and the data warehouse.'
                          visibility: public
                          category: finance
                          tags:
                            - invoice
                            - erp
                          latest_version: 1.2.0
                          latest_download_url: 'https://skills.rvnxx.test/api/v1/skills/revenexx/skills-catalog/invoice-sync/versions/1.2.0/download'
                examples:
                  -
                    data:
                      -
                        vendor: revenexx
                        name: invoice-sync
                        slug: revenexx/invoice-sync
                        title: 'Invoice Sync'
                        description: 'Sync invoices between Business Central and the data warehouse.'
                        visibility: public
                        category: finance
                        tags:
                          - invoice
                          - erp
                        latest_version: 1.2.0
                        latest_download_url: 'https://skills.rvnxx.test/api/v1/skills/revenexx/skills-catalog/invoice-sync/versions/1.2.0/download'
        401:
          description: 'Missing or invalid token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                examples:
                  -
                    message: Unauthenticated.
        403:
          description: 'No role in the public plane'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Token carries no roles in the public project.'
                examples:
                  -
                    message: 'Token carries no roles in the public project.'
      tags:
        - Skills
  /api/v1/skills/categories:
    get:
      summary: "List the distinct, non-empty skill categories visible to the caller's\norganisation. Powers the category filter on the browse page."
      operationId: listTheDistinctNonEmptySkillCategoriesVisibleToTheCallersOrganisationPowersTheCategoryFilterOnTheBrowsePage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                    examples:
                      -
                        - data
                        - devops
                        - finance
                examples:
                  -
                    data:
                      - data
                      - devops
                      - finance
      tags:
        - Skills
  /api/v1/skills/tags:
    get:
      summary: "List the distinct tags across skills visible to the caller's organisation."
      operationId: listTheDistinctTagsAcrossSkillsVisibleToTheCallersOrganisation
      description: 'Powers the multi-select tag filter on the browse page.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                    examples:
                      -
                        - ai
                        - cli
                        - erp
                        - invoice
                examples:
                  -
                    data:
                      - ai
                      - cli
                      - erp
                      - invoice
      tags:
        - Skills
  '/api/v1/skills/{vendor}/{repo}/{name}':
    get:
      summary: 'Show a single skill (by vendor + name) with its versions.'
      operationId: showASingleSkillbyVendor+NameWithItsVersions
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      vendor:
                        type: string
                        examples:
                          - revenexx
                      repo:
                        type: string
                        examples:
                          - skills-catalog
                      name:
                        type: string
                        examples:
                          - invoice-sync
                      slug:
                        type: string
                        examples:
                          - revenexx/skills-catalog/invoice-sync
                      title:
                        type: string
                        examples:
                          - 'Invoice Sync'
                      description:
                        type: string
                        examples:
                          - 'Sync invoices between Business Central and the data warehouse.'
                      visibility:
                        type: string
                        examples:
                          - public
                      category:
                        type: string
                        examples:
                          - finance
                      tags:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - invoice
                            - erp
                      keywords:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - invoice
                            - business-central
                      authors:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              examples:
                                - 'Jane Doe'
                            email:
                              type: string
                              examples:
                                - jane@revenexx.com
                        examples:
                          -
                            - name: 'Jane Doe'
                              email: jane@revenexx.com
                      homepage:
                        type: string
                        examples:
                          - 'https://docs.revenexx.com/skills/invoice-sync'
                      license:
                        type: string
                        examples:
                          - MIT
                      targets:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - claude-code
                            - cursor
                      allowed_tools:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - Bash
                            - Read
                      latest_version:
                        type: string
                        examples:
                          - 1.2.0
                      readme:
                        type: string
                        examples:
                          - "# Invoice Sync\n\nSyncs invoices…"
                      latest_download_url:
                        type: string
                        examples:
                          - 'https://skills.rvnxx.test/api/v1/skills/revenexx/skills-catalog/invoice-sync/versions/1.2.0/download'
                      versions:
                        type: array
                        items:
                          type: object
                          properties:
                            version:
                              type: string
                              examples:
                                - 1.2.0
                            description:
                              type: string
                              examples:
                                - 'Sync invoices between Business Central and the data warehouse.'
                            artifact_hash:
                              type: string
                              examples:
                                - 'sha256:7f3b1c9a2e4d5f6071829304a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e'
                            artifact_bytes:
                              type: integer
                              examples:
                                - 20480
                            registered_at:
                              type: string
                              examples:
                                - '2026-06-20T09:12:00Z'
                        examples:
                          -
                            - version: 1.2.0
                              description: 'Sync invoices between Business Central and the data warehouse.'
                              artifact_hash: 'sha256:7f3b1c9a2e4d5f6071829304a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e'
                              artifact_bytes: 20480
                              registered_at: '2026-06-20T09:12:00Z'
                examples:
                  -
                    data:
                      vendor: revenexx
                      repo: skills-catalog
                      name: invoice-sync
                      slug: revenexx/skills-catalog/invoice-sync
                      title: 'Invoice Sync'
                      description: 'Sync invoices between Business Central and the data warehouse.'
                      visibility: public
                      category: finance
                      tags:
                        - invoice
                        - erp
                      keywords:
                        - invoice
                        - business-central
                      authors:
                        -
                          name: 'Jane Doe'
                          email: jane@revenexx.com
                      homepage: 'https://docs.revenexx.com/skills/invoice-sync'
                      license: MIT
                      targets:
                        - claude-code
                        - cursor
                      allowed_tools:
                        - Bash
                        - Read
                      latest_version: 1.2.0
                      readme: "# Invoice Sync\n\nSyncs invoices…"
                      latest_download_url: 'https://skills.rvnxx.test/api/v1/skills/revenexx/skills-catalog/invoice-sync/versions/1.2.0/download'
                      versions:
                        -
                          version: 1.2.0
                          description: 'Sync invoices between Business Central and the data warehouse.'
                          artifact_hash: 'sha256:7f3b1c9a2e4d5f6071829304a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e'
                          artifact_bytes: 20480
                          registered_at: '2026-06-20T09:12:00Z'
        404:
          description: 'Skill not found or not visible to caller'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found.'
                examples:
                  -
                    message: 'Not Found.'
      tags:
        - Skills
    parameters:
      -
        in: path
        name: vendor
        description: 'The skill vendor (GitHub owner).'
        required: true
        schema:
          type: string
          examples:
            - revenexx
      -
        in: path
        name: repo
        description: 'The repository the skill lives in.'
        required: true
        schema:
          type: string
          examples:
            - skills-catalog
      -
        in: path
        name: name
        description: 'The skill name.'
        required: true
        schema:
          type: string
          examples:
            - invoice-sync
  '/api/v1/skills/{vendor}/{repo}/{name}/versions/{version}/download':
    get:
      summary: 'Stream the zip artifact for a specific version of a skill.'
      operationId: streamTheZipArtifactForASpecificVersionOfASkill
      description: "Serves both the CLI install and a direct zip download for any AI chat/agent\n(the registry is agent-agnostic, not Claude-only). The response body is the\nraw skill bundle streamed as an `application/zip` attachment named\n`{name}-{version}.zip` — it is not a JSON document."
      parameters: []
      responses:
        200:
          description: 'Skill bundle'
          content:
            text/plain:
              schema:
                type: string
                examples:
                  - 'Binary `application/zip` stream (Content-Disposition: attachment; filename="{name}-{version}.zip"). Not a JSON document.'
        404:
          description: 'Skill or version not found / not visible to caller'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found.'
                examples:
                  -
                    message: 'Not Found.'
      tags:
        - Skills
    parameters:
      -
        in: path
        name: vendor
        description: 'The skill vendor (GitHub owner).'
        required: true
        schema:
          type: string
          examples:
            - revenexx
      -
        in: path
        name: repo
        description: 'The repository the skill lives in.'
        required: true
        schema:
          type: string
          examples:
            - skills-catalog
      -
        in: path
        name: name
        description: 'The skill name.'
        required: true
        schema:
          type: string
          examples:
            - invoice-sync
      -
        in: path
        name: version
        description: 'The skill version to download.'
        required: true
        schema:
          type: string
          examples:
            - 1.2.0
  '/api/v1/skills/{vendor}/{repo}/{name}/versions/{version}':
    get:
      summary: "Show a single version of a skill, including that version's README."
      operationId: showASingleVersionOfASkillIncludingThatVersionsREADME
      description: "Unlike the skill detail endpoint (whose `readme` is always the latest\nversion's), this returns the README and metadata of the exact version\nrequested, plus parent-skill context (`title`, `latest_version`,\n`is_latest`) so the UI can flag when an older version is being viewed."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      version:
                        type: string
                        examples:
                          - 1.2.0
                      description:
                        type: string
                        examples:
                          - 'Sync invoices between Business Central and the data warehouse.'
                      readme:
                        type: string
                        examples:
                          - "# Invoice Sync\n\nSyncs invoices…"
                      visibility:
                        type: string
                        examples:
                          - public
                      allowed_tools:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - Bash
                            - Read
                      artifact_hash:
                        type: string
                        examples:
                          - 'sha256:7f3b1c9a2e4d5f6071829304a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e'
                      artifact_bytes:
                        type: integer
                        examples:
                          - 20480
                      source_ref:
                        type: string
                        examples:
                          - refs/tags/v1.2.0
                      registered_at:
                        type: string
                        examples:
                          - '2026-06-20T09:12:00Z'
                      title:
                        type: string
                        examples:
                          - 'Invoice Sync'
                      latest_version:
                        type: string
                        examples:
                          - 1.2.0
                      is_latest:
                        type: boolean
                        examples:
                          - true
                examples:
                  -
                    data:
                      version: 1.2.0
                      description: 'Sync invoices between Business Central and the data warehouse.'
                      readme: "# Invoice Sync\n\nSyncs invoices…"
                      visibility: public
                      allowed_tools:
                        - Bash
                        - Read
                      artifact_hash: 'sha256:7f3b1c9a2e4d5f6071829304a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e'
                      artifact_bytes: 20480
                      source_ref: refs/tags/v1.2.0
                      registered_at: '2026-06-20T09:12:00Z'
                      title: 'Invoice Sync'
                      latest_version: 1.2.0
                      is_latest: true
        404:
          description: 'Skill or version not found / not visible to caller'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found.'
                examples:
                  -
                    message: 'Not Found.'
      tags:
        - Skills
    parameters:
      -
        in: path
        name: vendor
        description: 'The skill vendor (GitHub owner).'
        required: true
        schema:
          type: string
          examples:
            - revenexx
      -
        in: path
        name: repo
        description: 'The repository the skill lives in.'
        required: true
        schema:
          type: string
          examples:
            - skills-catalog
      -
        in: path
        name: name
        description: 'The skill name.'
        required: true
        schema:
          type: string
          examples:
            - invoice-sync
      -
        in: path
        name: version
        description: 'The skill version.'
        required: true
        schema:
          type: string
          examples:
            - 1.2.0