Stacklok groups 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 groups API
  version: '0.1'
tags:
- name: groups
paths:
  /api/v1beta/groups:
    get:
      description: Get a list of all groups
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.groupListResponse'
          description: OK
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: List all groups
      tags:
      - groups
    post:
      description: Create a new group with the specified name
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.createGroupRequest'
                description: Group creation request
                summary: group
        description: Group creation request
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.createGroupResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                type: string
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Create a new group
      tags:
      - groups
  /api/v1beta/groups/{name}:
    delete:
      description: Delete a group by name.
      parameters:
      - description: Group name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: 'Delete all workloads in the group (default: false, moves workloads to default group)'
        in: query
        name: with-workloads
        schema:
          type: boolean
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: No Content
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Delete a group
      tags:
      - groups
    get:
      description: Get details of a specific group
      parameters:
      - description: Group name
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_groups.Group'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Get group details
      tags:
      - groups
components:
  schemas:
    pkg_api_v1.createGroupResponse:
      properties:
        name:
          description: Name of the created group
          type: string
      type: object
    pkg_api_v1.createGroupRequest:
      properties:
        name:
          description: Name of the group to create
          type: string
      type: object
    github_com_stacklok_toolhive_pkg_groups.Group:
      properties:
        name:
          type: string
        plugins:
          items:
            type: string
          type: array
          uniqueItems: false
        registered_clients:
          items:
            type: string
          type: array
          uniqueItems: false
        skills:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    pkg_api_v1.groupListResponse:
      properties:
        groups:
          description: List of groups
          items:
            $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_groups.Group'
          type: array
          uniqueItems: false
      type: object
  securitySchemes:
    BearerAuth:
      description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"'
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: ''
  url: ''