Stacklok v1 API

openapi: 3.1.0
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 clients v1 API
  version: '0.1'
tags:
- name: v1
paths:
  /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:
    get:
      description: 'Get the claims for an API-published entry name within the managed source.

        Claims are stored at the entry-name level and are shared by every version of that name.

        Synced-source entries (git/api/file/kubernetes) are out of scope: their claims come from

        upstream (the source manifest or the `toolhive.stacklok.dev/authz-claims` annotation) and

        are surfaced through the `/v1/sources/{name}/entries` and `/v1/registries/{name}/entries` lists.'
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_api_v1.entryClaimsResponse'
          description: Entry claims
        '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: Get entry claims
      tags:
      - v1
    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
      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
      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
      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
      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:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.RegistryCreateRequest'
                description: Registry configuration
                summary: request
        description: Registry configuration
        required: true
      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
      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
      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
      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
      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:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest'
                description: Source configuration
                summary: request
        description: Source configuration
        required: true
      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
      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
components:
  schemas:
    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.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.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_config.KubernetesConfig:
      description: Kubernetes discovery source
      type: object
    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
    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
    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
    model.ArgumentType:
      enum:
      - positional
      - named
      example: positional
      type: string
      x-enum-varnames:
      - ArgumentTypePositional
      - ArgumentTypeNamed
    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
    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
    internal_api_v1.updateEntryClaimsRequest:
      properties:
        claims:
          additionalProperties: {}
          type: object
      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.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
    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
    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
    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
    github_com_stacklok_toolhive-registry-server_internal_config.APIConfig:
      description: API endpoint source
      properties:
        endpoint:
          description: "Endpoint is the base API URL (without path)\nThe registry handler will append the appropriate paths for the MCP Registry API v0.1:\n  - /v0.1/servers - List all servers\n  - /v0.1/servers/{name}/versions - List server versions\n  - /v0.1/servers/{name}/versions/{version} - Get specific version\nExample: \"http://my-registry-api.default.svc.cluster.local/registry\""
          type: string
        timeout:
          description: 'Timeout is the per-request timeout for HTTP requests to the API endpoint

            Accepts a Go duration string (e.g., "30s", "1m"); must be > 0 and <= 5m

            Defaults to 10s if not specified

            Useful for public or occasionally-slow upstreams where the default is too aggressive'
          type: string
      type: object
    github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig:
      description: Managed registry (no sync)
      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.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.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_config.GitAuthConfig:
      description: Auth contains optional authentication for private repositories
      properties:
        passwordFile:
          description: 'PasswordFile is the path to a file containing the Git password/token

            Must be an absolute path; whitespace is trimmed from the content'
          type: string
        username:
          description: Username is the Git username for HTTP Basic authentication
          type: str

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stacklok/refs/heads/main/openapi/stacklok-v1-api-openapi.yml