Stacklok clients 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 API
  version: '0.1'
tags:
- name: clients
paths:
  /api/v1beta/clients:
    get:
      description: List all registered clients in ToolHive
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.RegisteredClient'
                type: array
          description: OK
      summary: List all clients
      tags:
      - clients
    post:
      description: Register a new client with ToolHive
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.createClientRequest'
                description: Client to register
                summary: client
        description: Client to register
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.createClientResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid request or unsupported client type
      summary: Register a new client
      tags:
      - clients
  /api/v1beta/clients/{name}:
    delete:
      description: Unregister a client from ToolHive
      parameters:
      - description: Client name to unregister
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid request or unsupported client type
      summary: Unregister a client
      tags:
      - clients
  /api/v1beta/clients/{name}/groups/{group}:
    delete:
      description: Unregister a client from a specific group in ToolHive
      parameters:
      - description: Client name to unregister
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Group name to remove client from
        in: path
        name: group
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid request or unsupported client type
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Client or group not found
      summary: Unregister a client from a specific group
      tags:
      - clients
  /api/v1beta/clients/register:
    post:
      description: Register multiple clients with ToolHive
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.bulkClientRequest'
                description: Clients to register
                summary: clients
        description: Clients to register
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/pkg_api_v1.createClientResponse'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid request or unsupported client type
      summary: Register multiple clients
      tags:
      - clients
  /api/v1beta/clients/unregister:
    post:
      description: Unregister multiple clients from ToolHive
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.bulkClientRequest'
                description: Clients to unregister
                summary: clients
        description: Clients to unregister
        required: true
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid request or unsupported client type
      summary: Unregister multiple clients
      tags:
      - clients
components:
  schemas:
    github_com_stacklok_toolhive_pkg_client.ClientApp:
      description: ClientType is the type of MCP client
      enum:
      - roo-code
      - cline
      - cursor
      - vscode-insider
      - vscode
      - claude-code
      - windsurf
      - windsurf-jetbrains
      - amp-cli
      - lm-studio
      - goose
      - trae
      - continue
      - opencode
      - kiro
      - antigravity
      - zed
      - gemini-cli
      - vscode-server
      - mistral-vibe
      - codex
      - kimi-cli
      - factory
      - copilot-cli
      type: string
      x-enum-varnames:
      - RooCode
      - Cline
      - Cursor
      - VSCodeInsider
      - VSCode
      - ClaudeCode
      - Windsurf
      - WindsurfJetBrains
      - AmpCli
      - LMStudio
      - Goose
      - Trae
      - Continue
      - OpenCode
      - Kiro
      - Antigravity
      - Zed
      - GeminiCli
      - VSCodeServer
      - MistralVibe
      - Codex
      - KimiCli
      - Factory
      - CopilotCli
    pkg_api_v1.bulkClientRequest:
      properties:
        groups:
          description: Groups is the list of groups configured on the client.
          items:
            type: string
          type: array
          uniqueItems: false
        names:
          description: Names is the list of client names to operate on.
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.ClientApp'
          type: array
          uniqueItems: false
      type: object
    pkg_api_v1.createClientResponse:
      properties:
        groups:
          description: Groups is the list of groups configured on the client.
          items:
            type: string
          type: array
          uniqueItems: false
        name:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.ClientApp'
      type: object
    pkg_api_v1.createClientRequest:
      properties:
        groups:
          description: Groups is the list of groups configured on the client.
          items:
            type: string
          type: array
          uniqueItems: false
        name:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.ClientApp'
      type: object
    github_com_stacklok_toolhive_pkg_client.RegisteredClient:
      properties:
        groups:
          items:
            type: string
          type: array
          uniqueItems: false
        name:
          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.ClientApp'
      type: object
  securitySchemes:
    BearerAuth:
      description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"'
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: ''
  url: ''