swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates cluster-groups API
  version: '1.0'
tags:
- name: cluster-groups
paths:
  /1.0/cluster/groups:
    get:
      description: Returns a list of cluster groups (URLs).
      operationId: cluster_groups_get
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/cluster/groups/server01\",\n  \"/1.0/cluster/groups/server02\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster groups
      tags:
      - cluster-groups
  /1.0/cluster/groups/{name}:
    delete:
      description: Removes the cluster group.
      operationId: cluster_group_delete
      parameters:
      - description: Cluster group name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the cluster group.
      tags:
      - cluster-groups
    get:
      description: Gets a specific cluster group.
      operationId: cluster_group_get
      parameters:
      - description: Cluster group name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Cluster group
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ClusterGroup'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster group
      tags:
      - cluster-groups
    patch:
      consumes:
      - application/json
      description: Updates the cluster group configuration.
      operationId: cluster_group_patch
      parameters:
      - description: Cluster group name
        in: path
        name: name
        required: true
        type: string
      - description: cluster group configuration
        in: body
        name: cluster group
        required: true
        schema:
          $ref: '#/definitions/ClusterGroupPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the cluster group
      tags:
      - cluster-groups
    post:
      consumes:
      - application/json
      description: Renames an existing cluster group.
      operationId: cluster_group_post
      parameters:
      - description: Cluster group name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster group rename request
        in: body
        name: name
        required: true
        schema:
          $ref: '#/definitions/ClusterGroupPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename the cluster group
      tags:
      - cluster-groups
    put:
      consumes:
      - application/json
      description: Updates the entire cluster group configuration.
      operationId: cluster_group_put
      parameters:
      - description: Cluster group name
        in: path
        name: name
        required: true
        type: string
      - description: cluster group configuration
        in: body
        name: cluster group
        required: true
        schema:
          $ref: '#/definitions/ClusterGroupPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the cluster group
      tags:
      - cluster-groups
  /1.0/cluster/groups?recursion=1:
    get:
      description: Returns a list of cluster groups (structs).
      operationId: cluster_groups_get_recursion1
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of cluster groups
                items:
                  $ref: '#/definitions/ClusterGroup'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster groups
      tags:
      - cluster-groups
definitions:
  ClusterGroupPost:
    properties:
      name:
        description: The new name of the cluster group
        example: group1
        type: string
        x-go-name: Name
    title: ClusterGroupPost represents the fields required to rename a cluster group.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterGroupPut:
    properties:
      config:
        description: Cluster group configuration map
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: The description of the cluster group
        example: amd64 servers
        type: string
        x-go-name: Description
      members:
        description: List of members in this group
        example:
        - server01
        - server02
        items:
          type: string
        type: array
        x-go-name: Members
    title: ClusterGroupPut represents the modifiable fields of a cluster group.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterGroup:
    properties:
      config:
        description: Cluster group configuration map
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: The description of the cluster group
        example: amd64 servers
        type: string
        x-go-name: Description
      members:
        description: List of members in this group
        example:
        - server01
        - server02
        items:
          type: string
        type: array
        x-go-name: Members
      name:
        description: The new name of the cluster group
        example: group1
        type: string
        x-go-name: Name
      used_by:
        description: List of URLs of objects using this cluster group
        example:
        - /1.0/cluster/members/server01
        - /1.0/project/default
        items:
          type: string
        readOnly: true
        type: array
        x-go-name: UsedBy
    title: ClusterGroup represents a cluster group.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
responses:
  Forbidden:
    description: Forbidden
    schema:
      properties:
        error:
          example: not authorized
          type: string
          x-go-name: Error
        error_code:
          example: 403
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  BadRequest:
    description: Bad Request
    schema:
      properties:
        error:
          example: bad request
          type: string
          x-go-name: Error
        error_code:
          example: 400
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  EmptySyncResponse:
    description: Empty sync response
    schema:
      properties:
        status:
          example: Success
          type: string
          x-go-name: Status
        status_code:
          example: 200
          format: int64
          type: integer
          x-go-name: StatusCode
        type:
          example: sync
          type: string
          x-go-name: Type
      type: object
  PreconditionFailed:
    description: Precondition Failed
    schema:
      properties:
        error:
          example: precondition failed
          type: string
          x-go-name: Error
        error_code:
          example: 412
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  InternalServerError:
    description: Internal Server Error
    schema:
      properties:
        error:
          example: internal server error
          type: string
          x-go-name: Error
        error_code:
          example: 500
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object