Stacklok v1 API

openapi: 3.2.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_config.GitConfig:
      description: Git repository source
      properties:
        auth:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitAuthConfig'
        branch:
          description: Branch is the Git branch to use (mutually exclusive with Tag and Commit)
          type: string
        commit:
          description: Commit is the Git commit SHA to use (mutually exclusive with Branch and Tag)
          type: string
        path:
          description: Path is the path to the registry file within the repository
          type: string
        repository:
          description: Repository is the Git repository URL (HTTP/HTTPS/SSH)
          type: string
        tag:
          description: Tag is the Git tag to use (mutually exclusive with Branch and Commit)
          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_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
    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
    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:\n  - For NPM/PyPI/NuGet: package name or ID\n  - For OCI: full image reference (e.g., \"ghcr.io/owner/repo:v1.0.0\")\n  - 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, cargo; 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", "cargo", "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
    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
    github_com_stacklok_toolhive-registry-server_internal_service.SkillIcon:
      properties:
        label:
          type: string
        size:
          type: string
        src:
          type: string
        type:
          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.CreationType:
      description: API or CONFIG
      enum:
      - API
      - CONFIG
      type: string
      x-enum-varnames:
      - CreationTypeAPI
      - CreationTypeCONFIG
    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
    github_com_stacklok_toolhive-registry-server_internal_service.SkillRepository:
      properties:
        type:
          type: string
        url:
          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
    github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest:
      properties:
        api:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.APIConfig'
        claims:
          additionalProperties: {}
          description: Authorization claims
          type: object
        file:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FileConfig'
        filter:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig'
        git:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitConfig'
        kubernetes:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.KubernetesConfig'
        managed:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig'
        syncPolicy:
          $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SyncPolicyConfig'
      type: object
    github_com_stacklok_toolhive-registry-server_internal_service.RegistryCreateRequest:
      properties:
        claims:
          additionalProperties: {}
          description: Authorization claims
          type: object
        sources:
          description: ordered list of source names
          items:
            type: string
          type: array
          uniqueItems: false
      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_config.FileConfig:
      description: Local file or URL source
      properties:
        data:
          description: 'Data is the inline registry data as a JSON string

            Mutually exclusive with Path and URL - exactly one must be specified

            Useful for API-created registries where the data is provided directly'
          type: string
        path:
          description: 'Path is the path to the registry.json file on the local filesystem

            Can be absolute or relative to the working directory

            Mutually exclusive with URL and Data - exactly one must be specified'
          type: string
        timeout:
          description: 'Timeout is the timeout for HTTP requests when using URL

            Defaults to 30s if not specified

            Only applicable when URL is set'
          type: string
        url:
          description: 'URL is the HTTP/HTTPS URL to fetch the registry file from

            Mutually exclusive with Path and Data - exactly one must be specified

            HTTPS is required unless the host is localhost or THV_REGISTRY_INSECURE_URL=true'
          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
  

# --- 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