swagger.yaml

components:
  schemas:
    github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig:
      description: Filtering rules
      properties:
        names:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig'
        tags:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig'
      type: object
    github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig:
      properties:
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_config.SourceType:
      description: git, api, file, managed, kubernetes
      enum:
      - git
      - api
      - file
      - managed
      - kubernetes
      type: string
      x-enum-varnames:
      - SourceTypeGit
      - SourceTypeAPI
      - SourceTypeFile
      - SourceTypeManaged
      - SourceTypeKubernetes
    github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig:
      properties:
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.CreationType:
      description: API or CONFIG
      enum:
      - API
      - CONFIG
      type: string
      x-enum-varnames:
      - CreationTypeAPI
      - CreationTypeCONFIG
    github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo:
      properties:
        createdAt:
          type: string
        description:
          type: string
        title:
          type: string
        updatedAt:
          type: string
        version:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntriesResponse:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntryInfo'
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntryInfo:
      properties:
        createdAt:
          type: string
        description:
          type: string
        entryType:
          type: string
        name:
          type: string
        position:
          type: integer
        sourceName:
          type: string
        title:
          type: string
        updatedAt:
          type: string
        version:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo:
      properties:
        claims:
          additionalProperties: {}
          type: object
        createdAt:
          type: string
        creationType:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.CreationType'
        name:
          type: string
        sources:
          items:
            type: string
          type: array
          uniqueItems: false
        updatedAt:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.Skill:
      properties:
        _meta:
          additionalProperties: {}
          type: object
        allowedTools:
          items:
            type: string
          type: array
          uniqueItems: false
        compatibility:
          type: string
        createdAt:
          type: string
        description:
          type: string
        icons:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillIcon'
          type: array
          uniqueItems: false
        id:
          type: string
        isLatest:
          type: boolean
        license:
          type: string
        metadata:
          additionalProperties: {}
          type: object
        name:
          type: string
        namespace:
          type: string
        packages:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillPackage'
          type: array
          uniqueItems: false
        repository:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SkillRepository'
        status:
          type: string
        title:
          type: string
        updatedAt:
          type: string
        version:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SkillIcon:
      properties:
        label:
          type: string
        size:
          type: string
        src:
          type: string
        type:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SkillPackage:
      properties:
        commit:
          type: string
        digest:
          type: string
        identifier:
          type: string
        mediaType:
          type: string
        ref:
          type: string
        registryType:
          type: string
        subfolder:
          type: string
        url:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SkillRepository:
      properties:
        type:
          type: string
        url:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo'
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo:
      properties:
        claims:
          additionalProperties: {}
          type: object
        entryType:
          type: string
        name:
          type: string
        versions:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo'
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo:
      properties:
        claims:
          additionalProperties: {}
          description: Authorization claims
          type: object
        createdAt:
          type: string
        creationType:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.CreationType'
        filterConfig:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig'
        name:
          type: string
        sourceConfig:
          description: Type-specific source configuration
        sourceType:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SourceType'
        syncSchedule:
          description: Sync interval string
          type: string
        syncStatus:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus'
        type:
          description: MANAGED, FILE, REMOTE, KUBERNETES
          type: string
        updatedAt:
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse:
      properties:
        sources:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus:
      properties:
        attemptCount:
          description: Number of sync attempts
          type: integer
        lastAttempt:
          description: Last sync attempt
          type: string
        lastSyncTime:
          description: Last completed sync attempt
          type: string
        message:
          description: Status or error message
          type: string
        phase:
          description: complete, syncing, failed
          type: string
        serverCount:
          description: Number of servers in registry
          type: integer
        skillCount:
          description: Number of skills in registry
          type: integer
      type: object
    internal_api_v1.meResponse:
      properties:
        roles:
          items:
            type: string
          type: array
          uniqueItems: false
        subject:
          type: string
      type: object
    internal_api_v1.publishEntryRequest:
      properties:
        claims:
          additionalProperties: {}
          type: object
        server:
          $ref: '#/components/schemas/v0.ServerJSON'
        skill:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.Skill'
      type: object
    internal_api_v1.registryListResponse:
      properties:
        registries:
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo'
          type: array
          uniqueItems: false
      type: object
    internal_api_v1.updateEntryClaimsRequest:
      properties:
        claims:
          additionalProperties: {}
          type: object
      type: object
    internal_api_x_skills.SkillListMetadata:
      properties:
        count:
          type: integer
        nextCursor:
          type: string
      type: object
    internal_api_x_skills.SkillListResponse:
      properties:
        metadata:
          $ref: '#/components/schemas/internal_api_x_skills.SkillListMetadata'
        skills:
          items:
            $ref: '#/components/schemas/registry.Skill'
          type: array
          uniqueItems: false
      type: object
    model.Argument:
      properties:
        choices:
          items:
            type: string
          type: array
          uniqueItems: false
        default:
          type: string
        description:
          type: string
        format:
          $ref: '#/components/schemas/model.Format'
        isRepeated:
          type: boolean
        isRequired:
          type: boolean
        isSecret:
          type: boolean
        name:
          example: --port
          type: string
        placeholder:
          type: string
        type:
          $ref: '#/components/schemas/model.ArgumentType'
        value:
          type: string
        valueHint:
          example: file_path
          type: string
        variables:
          additionalProperties:
            $ref: '#/components/schemas/model.Input'
          type: object
      type: object
    model.ArgumentType:
      enum:
      - positional
      - named
      example: positional
      type: string
      x-enum-varnames:
      - ArgumentTypePositional
      - ArgumentTypeNamed
    model.Format:
      enum:
      - string
      - number
      - boolean
      - filepath
      type: string
      x-enum-varnames:
      - FormatString
      - FormatNumber
      - FormatBoolean
      - FormatFilePath
    model.Icon:
      properties:
        mimeType:
          example: image/png
          type: string
        sizes:
          items:
            type: string
          type: array
          uniqueItems: false
        src:
          example: https://example.com/icon.png
          format: uri
          maxLength: 255
          type: string
        theme:
          type: string
      type: object
    model.Input:
      properties:
        choices:
          items:
            type: string
          type: array
          uniqueItems: false
        default:
          type: string
        description:
          type: string
        format:
          $ref: '#/components/schemas/model.Format'
        isRequired:
          type: boolean
        isSecret:
          type: boolean
        placeholder:
          type: string
        value:
          type: string
      type: object
    model.KeyValueInput:
      properties:
        choices:
          items:
            type: string
          type: array
          uniqueItems: false
        default:
          type: string
        description:
          type: string
        format:
          $ref: '#/components/schemas/model.Format'
        isRequired:
          type: boolean
        isSecret:
          type: boolean
        name:
          example: SOME_VARIABLE
          type: string
        placeholder:
          type: string
        value:
          type: string
        variables:
          additionalProperties:
            $ref: '#/components/schemas/model.Input'
          type: object
      type: object
    model.Package:
      properties:
        environmentVariables:
          description: EnvironmentVariables are set when running the package
          items:
            $ref: '#/components/schemas/model.KeyValueInput'
          type: array
          uniqueItems: false
        fileSha256:
          description: FileSHA256 is the SHA-256 hash for integrity verification (required
            for mcpb, optional for others)
          example: fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce
          pattern: ^[a-f0-9]{64}$
          type: string
        identifier:
          description: |-
            Identifier is the package identifier:
              - For NPM/PyPI/NuGet: package name or ID
              - For OCI: full image reference (e.g., "ghcr.io/owner/repo:v1.0.0")
              - For MCPB: direct download URL
          example: '@modelcontextprotocol/server-brave-search'
          minLength: 1
          type: string
        packageArguments:
          description: PackageArguments are passed to the package's binary
          items:
            $ref: '#/components/schemas/model.Argument'
          type: array
          uniqueItems: false
        registryBaseUrl:
          description: RegistryBaseURL is the base URL of the package registry (used
            by npm, pypi, nuget; not used by oci, mcpb)
          example: https://registry.npmjs.org
          format: uri
          type: string
        registryType:
          description: RegistryType indicates how to download packages (e.g., "npm",
            "pypi", "oci", "nuget", "mcpb")
          example: npm
          minLength: 1
          type: string
        runtimeArguments:
          description: RuntimeArguments are passed to the package's runtime command
            (e.g., docker, npx)
          items:
            $ref: '#/components/schemas/model.Argument'
          type: array
          uniqueItems: false
        runtimeHint:
          description: RunTimeHint suggests the appropriate runtime for the package
          example: npx
          type: string
        transport:
          $ref: '#/components/schemas/model.Transport'
        version:
          description: Version is the package version (required for npm, pypi, nuget;
            optional for mcpb; not used by oci where version is in the identifier)
          example: 1.0.2
          maxLength: 255
          minLength: 1
          type: string
      type: object
    model.Repository:
      properties:
        id:
          example: b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9
          type: string
        source:
          example: github
          type: string
        subfolder:
          example: src/everything
          type: string
        url:
          example: https://github.com/modelcontextprotocol/servers
          format: uri
          type: string
      type: object
    model.Status:
      enum:
      - active
      - deprecated
      - deleted
      type: string
      x-enum-varnames:
      - StatusActive
      - StatusDeprecated
      - StatusDeleted
    model.Transport:
      description: Transport is required and specifies the transport protocol configuration
      properties:
        headers:
          items:
            $ref: '#/components/schemas/model.KeyValueInput'
          type: array
          uniqueItems: false
        type:
          example: stdio
          type: string
        url:
          example: https://api.example.com/mcp
          type: string
        variables:
          additionalProperties:
            $ref: '#/components/schemas/model.Input'
          type: object
      type: object
    registry.Skill:
      properties:
        _meta:
          additionalProperties: {}
          description: Meta is an opaque payload with extended meta data details of
            the skill.
          type: object
        allowedTools:
          description: |-
            AllowedTools is the list of tools that the skill is compatible with.
            This is experimental.
          items:
            type: string
          type: array
          uniqueItems: false
        compatibility:
          description: Compatibility is the environment requirements of the skill.
          type: string
        description:
          description: Description is the description of the skill.
          type: string
        icons:
          description: Icons is the list of icons for the skill.
          items:
            $ref: '#/components/schemas/registry.SkillIcon'
          type: array
          uniqueItems: false
        license:
          description: License is the SPDX license identifier of the skill.
          type: string
        metadata:
          additionalProperties: {}
          description: |-
            Metadata is the official metadata of the skill as reported in the
            SKILL.md file.
          type: object
        name:
          description: |-
            Name is the name of the skill.
            The format is that of identifiers, e.g. "my-skill".
          type: string
        namespace:
          description: |-
            Namespace is the namespace of the skill.
            The format is reverse-DNS, e.g. "io.github.user".
          type: string
        packages:
          description: Packages is the list of packages for the skill.
          items:
            $ref: '#/components/schemas/registry.SkillPackage'
          type: array
          uniqueItems: false
        repository:
          $ref: '#/components/schemas/registry.SkillRepository'
        status:
          description: |-
            Status is the status of the skill.
            Can be one of "active", "deprecated", or "archived".
          type: string
        title:
          description: |-
            Title is the title of the skill.
            This is for human consumption, not an identifier.
          type: string
        version:
          description: |-
            Version is the version of the skill.
            Any non-empty string is valid, but ideally it should be either a
            semantic version or a commit hash.
          type: string
      type: object
    registry.SkillIcon:
      properties:
        label:
          description: Label is the label of the icon.
          type: string
        size:
          description: Size is the size of the icon.
          type: string
        src:
          description: Src is the source of the icon.
          type: string
        type:
          description: Type is the type of the icon.
          type: string
      type: object
    registry.SkillPackage:
      properties:
        commit:
          description: Commit is the commit of the package.
          type: string
        digest:
          description: Digest is the digest of the package.
          type: string
        identifier:
          description: Identifier is the OCI identifier of the package.
          type: string
        mediaType:
          description: MediaType is the media type of the package.
          type: string
        ref:
          description: Ref is the reference of the package.
          type: string
        registryType:
          description: |-
            RegistryType is the type of registry the package is from.
            Can be "oci" or "git".
          type: string
        subfolder:
          description: Subfolder is the subfolder of the package.
          type: string
        url:
          description: URL is the URL of the package.
          type: string
      type: object
    registry.SkillRepository:
      description: Repository is the source repository of the skill.
      properties:
        type:
          description: Type is the type of the repository.
          type: string
        url:
          description: URL is the URL of the repository.
          type: string
      type: object
    v0.Metadata:
      properties:
        count:
          type: integer
        nextCursor:
          type: string
      type: object
    v0.RegistryExtensions:
      properties:
        isLatest:
          type: boolean
        publishedAt:
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/model.Status'
        statusChangedAt:
          format: date-time
          type: string
        statusMessage:
          type: string
        updatedAt:
          format: date-time
          type: string
      type: object
    v0.ResponseMeta:
      properties:
        io.modelcontextprotocol.registry/official:
          $ref: '#/components/schemas/v0.RegistryExtensions'
      type: object
    v0.ServerJSON:
      properties:
        $schema:
          example: https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json
          format: uri
          minLength: 1
          type: string
        _meta:
          $ref: '#/components/schemas/v0.ServerMeta'
        description:
          example: MCP server providing weather data and forecasts via OpenWeatherMap
            API
          maxLength: 100
          minLength: 1
          type: string
        icons:
          items:
            $ref: '#/components/schemas/model.Icon'
          type: array
          uniqueItems: false
        name:
          example: io.github.user/weather
          maxLength: 200
          minLength: 3
          pattern: ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$
          type: string
        packages:
          items:
            $ref: '#/components/schemas/model.Package'
          type: array
          uniqueItems: false
        remotes:
          items:
            $ref: '#/components/schemas/model.Transport'
          type: array
          uniqueItems: false
        repository:
          $ref: '#/components/schemas/model.Repository'
        title:
          example: Weather API
          maxLength: 100
          minLength: 1
          type: string
        version:
          example: 1.0.2
          maxLength: 255
          minLength: 1
          type: string
        websiteUrl:
          example: https://modelcontextprotocol.io/examples
          format: uri
          type: string
      type: object
    v0.ServerListResponse:
      properties:
        metadata:
          $ref: '#/components/schemas/v0.Metadata'
        servers:
          items:
            $ref: '#/components/schemas/v0.ServerResponse'
          type: array
          uniqueItems: false
      type: object
    v0.ServerMeta:
      properties:
        io.modelcontextprotocol.registry/publisher-provided:
          additionalProperties: {}
          type: object
      type: object
    v0.ServerResponse:
      properties:
        _meta:
          $ref: '#/components/schemas/v0.ResponseMeta'
        server:
          $ref: '#/components/schemas/v0.ServerJSON'
      type: object
  securitySchemes:
    BearerAuth:
      description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"'
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: ""
  url: ""
info:
  contact:
    url: https://github.com/stacklok/toolhive
  description: |-
    API for accessing MCP server registry data and deployed server information
    This API provides endpoints to query the MCP (Model Context Protocol) server registry,
    get information about available servers, and check the status of deployed servers.

    Authentication is required by default. Use Bearer token authentication with a valid
    OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides
    OAuth discovery metadata (RFC 9728).
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: ToolHive Registry API
  version: "0.1"
openapi: 3.1.0
paths:
  /openapi.json:
    get:
      description: Get the OpenAPI 3.1.0 specification for this API
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: OpenAPI 3.1.0 specification
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal Server Error
      summary: OpenAPI specification
      tags:
      - system
  /registry/{registryName}/v0.1/servers:
    get:
      description: Get a list of available servers from a specific registry
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Pagination cursor for retrieving next set of results
        in: query
        name: cursor
        schema:
          type: string
      - description: Maximum number of items to return
        in: query
        name: limit
        schema:
          type: integer
      - description: Search servers by name (substring match)
        in: query
        name: search
        schema:
          type: string
      - description: Filter by version ('latest' for latest version, or an exact version
          like '1.2.3')
        in: query
        name: version
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerListResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry not found
      security:
      - BearerAuth: []
      summary: List servers in specific registry
      tags:
      - registry
  /registry/{registryName}/v0.1/servers/{serverName}/versions:
    get:
      description: Returns all available versions for a specific MCP server from a
        specific registry
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: URL-encoded server name (e.g., \
        in: path
        name: serverName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerListResponse'
          description: A list of all versions for the server
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Server not found
      security:
      - BearerAuth: []
      summary: List all versions of an MCP server in specific registry
      tags:
      - registry
  /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}:
    get:
      description: |-
        Returns detailed information about a specific version of an MCP server from a specific registry.
        Use the special version `latest` to get the latest version.
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: URL-encoded server name (e.g., \
        in: path
        name: serverName
        required: true
        schema:
          type: string
      - description: URL-encoded version to retrieve (e.g., \
        in: path
        name: version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerResponse'
          description: Detailed server information
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Server or version not found
      security:
      - BearerAuth: []
      summary: Get specific MCP server version in specific registry
      tags:
      - registry
  /registry/{registryName}/v0.1/x/dev.toolhive/skills:
    get:
      description: List skills in a registry (paginated, latest versions).
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Filter by name/description substring
        in: query
        name: search
        schema:
          type: string
      - description: Filter by status (comma-separated, e.g. active,deprecated)
        in: query
        name: status
        schema:
          type: string
      - description: Max results (default 50, max 100)
        in: query
        name: limit
        schema:
          type: integer
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_api_x_skills.SkillListResponse'
          description: List of skills
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      security:
      - BearerAuth: []
      summary: List skills in registry
      tags:
      - skills
  /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}:
    get:
      description: Get the latest version of a skill by namespace and name.
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Skill namespace (reverse-DNS)
        in: path
        name: namespace
        required: true
        schema:
          type: string
      - description: Skill name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry.Skill'
          description: Skill details
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Skill not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      security:
      - BearerAuth: []
      summary: Get latest skill version
      tags:
      - skills
  /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions:
    get:
      description: List all versions of a skill.
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Skill namespace (reverse-DNS)
        in: path
        name: namespace
        required: true
        schema:
          type: string
      - description: Skill name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_api_x_skills.SkillListResponse'
          description: List of skill versions
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Skill not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      security:
      - BearerAuth: []
      summary: List skill versions
      tags:
      - skills
  /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}:
    get:
      description: Get a specific version of a skill.
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Skill namespace (reverse-DNS)
        in: path
        name: namespace
        required: true
        schema:
          type: string
      - description: Skill name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Skill version
        in: path
        name: version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry.Skill'
          description: Skill details
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Skill or version not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      security:
      - BearerAuth: []
      summary: Get specific skill version
      tags:
      - skills
  /v1/entries:
    post:
      description: Publish a new server or skill entry. Exactly one of 'server' or
        'skill' must be provided.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/internal_api_v1.publishEntryRequest'
                description: Entry to publish (server or skill)
                summary: request
        description: Entry to publish (server or skill)
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                type: object
          description: Published entry (server or skill)
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "409":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Publish entry
      tags:
      - v1
  /v1/entries/{type}/{name}/claims:
    put:
      description: Update claims for a published entry name
      parameters:
      - description: Entry Type (server or skill)
        in: path
        name: type
        required: true
        schema:
          type: string
      - description: Entry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/internal_api_v1.updateEntryClaimsRequest'
                description: Claims to set
                summary: request
        description: Claims to set
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "403":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
        "503":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: No managed source available
      summary: Update entry claims
      tags:
      - v1
  /v1/entries/{type}/{name}/versions/{version}:
    delete:
      description: Delete a published entry version
      parameters:
      - description: Entry Type (server or skill)
        in: path
        name: type
        required: true
        schema:
          type: string
      - description: Entry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Version
        in: path
        name: version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Delete published entry
      tags:
      - v1
  /v1/me:
    get:
      description: Returns the authenticated caller's identity and roles
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_api_v1.meResponse'
          description: Caller identity and roles
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
      summary: Get current user info
      tags:
      - v1
  /v1/registries:
    get:
      description: List all registries
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_api_v1.registryListResponse'
          description: Registries list
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: List registries
      tags:
      - v1
  /v1/registries/{name}:
    delete:
      description: Delete a registry by name
      parameters:
      - description: Registry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "204":
          description: Registry deleted
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "403":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Cannot modify config-created registry
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Delete registry
      tags:
      - v1
    get:
      description: Get a registry by name
      parameters:
      - description: Registry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo'
          description: Registry details
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Get registry
      tags:
      - v1
    put:
      description: Create a new registry or update an existing one
      parameters:
      - description: Registry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo'
          description: Registry updated
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryInfo'
          description: Registry created
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "403":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Cannot modify config-created registry
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Create or update registry
      tags:
      - v1
  /v1/registries/{name}/entries:
    get:
      description: List all entries for a registry
      parameters:
      - description: Registry Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryEntriesResponse'
          description: Registry entries
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: List registry entries
      tags:
      - v1
  /v1/sources:
    get:
      description: List all sources
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse'
          description: Sources list
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: List sources
      tags:
      - v1
  /v1/sources/{name}:
    delete:
      description: Delete a source by name
      parameters:
      - description: Source Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "204":
          description: Source deleted
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "403":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Cannot modify config-created source
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Source not found
        "409":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Source in use
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Delete source
      tags:
      - v1
    get:
      description: Get a source by name
      parameters:
      - description: Source Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
          description: Source details
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Source not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Get source
      tags:
      - v1
    put:
      description: Create a new source or update an existing one
      parameters:
      - description: Source Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
          description: Source updated
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
          description: Source created
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "403":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Cannot modify config-created source
        "409":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Managed source limit reached
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: Create or update source
      tags:
      - v1
  /v1/sources/{name}/entries:
    get:
      description: List all entries for a source
      parameters:
      - description: Source Name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse'
          description: Source entries
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Source not found
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal server error
      summary: List source entries
      tags:
      - v1