openapi: 3.2.0
info:
  title: SingleStore Management Workspace Groups API
  description: The SingleStore Management API is a REST interface for programmatically creating and managing workspace groups and workspaces within SingleStore Helios, the cloud-managed distributed SQL database service.
  version: v1
  contact:
    name: SingleStore Support
    url: https://support.singlestore.com
  termsOfService: https://www.singlestore.com/cloud-terms-and-conditions/
servers:
- url: https://api.singlestore.com/v1
  description: SingleStore Helios Production Server
security:
- bearerAuth: []
tags:
- name: Workspace Groups
  description: Create, list, retrieve, update, and delete workspace groups within a SingleStore Helios organization. Workspace groups are logical containers that group workspaces by region and network configuration.
paths:
  /workspaceGroups:
    get:
      operationId: listWorkspaceGroups
      summary: List Workspace Groups
      description: Retrieves all workspace groups accessible to the authenticated user within the current organization. Returns a list of workspace group objects including their IDs, names, regions, states, and configuration.
      tags:
      - Workspace Groups
      parameters:
      - $ref: '#/components/parameters/organizationIDQuery'
      responses:
        '200':
          description: List of workspace groups returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkspaceGroup
      summary: Create a Workspace Group
      description: Creates a new workspace group in the specified cloud region for the authenticated user's organization. A workspace group defines the network boundary, region, and firewall configuration for workspaces deployed within it.
      tags:
      - Workspace Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceGroupCreate'
      responses:
        '200':
          description: Workspace group created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaceGroups/{workspaceGroupID}:
    get:
      operationId: getWorkspaceGroup
      summary: Get a Workspace Group
      description: Retrieves detailed information about a specific workspace group identified by its unique ID, including its current state, region, firewall configuration, and associated metadata.
      tags:
      - Workspace Groups
      parameters:
      - $ref: '#/components/parameters/workspaceGroupIDPath'
      responses:
        '200':
          description: Workspace group returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWorkspaceGroup
      summary: Update a Workspace Group
      description: Updates the configuration of an existing workspace group, such as its name or firewall IP allowlist rules. Only the fields provided in the request body are modified; omitted fields remain unchanged.
      tags:
      - Workspace Groups
      parameters:
      - $ref: '#/components/parameters/workspaceGroupIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceGroupUpdate'
      responses:
        '200':
          description: Workspace group updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: terminateWorkspaceGroup
      summary: Terminate a Workspace Group
      description: Terminates and permanently deletes the specified workspace group and all workspaces within it. This operation is irreversible. Use the force parameter to bypass safety checks when the group contains active workspaces.
      tags:
      - Workspace Groups
      parameters:
      - $ref: '#/components/parameters/workspaceGroupIDPath'
      - name: force
        in: query
        description: When set to true, terminates the workspace group even if it contains active workspaces.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Workspace group terminated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceGroupDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    workspaceGroupIDPath:
      name: workspaceGroupID
      in: path
      required: true
      description: Unique identifier of the workspace group.
      schema:
        type: string
        format: uuid
    organizationIDQuery:
      name: organizationID
      in: query
      description: Filter results to a specific organization when the authenticated user belongs to multiple organizations.
      schema:
        type: string
        format: uuid
  schemas:
    WorkspaceGroupDeleteResponse:
      type: object
      description: Response returned after initiating workspace group termination.
      properties:
        workspaceGroupID:
          type: string
          format: uuid
          description: Unique identifier of the workspace group that was terminated.
    Error:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: HTTP status code of the error.
        message:
          type: string
          description: Human-readable description of the error.
    WorkspaceGroupUpdate:
      type: object
      description: Request body for updating an existing workspace group.
      properties:
        name:
          type: string
          description: Updated name for the workspace group.
        firewallRanges:
          type: array
          description: Updated list of CIDR IP ranges permitted to connect to workspaces.
          items:
            type: string
        allowAllTraffic:
          type: boolean
          description: When true, allows all inbound traffic regardless of firewall range configuration.
        expiresAt:
          type: string
          format: date-time
          description: Updated expiration timestamp after which the workspace group is automatically terminated.
    WorkspaceGroupCreate:
      type: object
      description: Request body for creating a new workspace group.
      required:
      - name
      - regionID
      properties:
        name:
          type: string
          description: Human-readable name for the new workspace group.
        regionID:
          type: string
          description: Cloud provider region where the workspace group will be deployed.
        firewallRanges:
          type: array
          description: CIDR IP ranges permitted to connect to workspaces in this group. Use 0.0.0.0/0 to allow all traffic.
          items:
            type: string
        allowAllTraffic:
          type: boolean
          description: When true, allows all inbound traffic to workspaces in this group.
        adminPassword:
          type: string
          description: Initial administrator password for the workspace group database. Must meet SingleStore password complexity requirements.
        expiresAt:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp after which the workspace group will be automatically terminated.
    WorkspaceGroup:
      type: object
      description: A workspace group is a logical container that groups workspaces sharing a common cloud region, network configuration, and firewall rules within a SingleStore Helios organization.
      properties:
        workspaceGroupID:
          type: string
          format: uuid
          description: Unique identifier of the workspace group.
        name:
          type: string
          description: Human-readable name of the workspace group.
        state:
          type: string
          description: Current lifecycle state of the workspace group.
          enum:
          - Active
          - Pending
          - Terminated
          - Failed
        regionID:
          type: string
          description: Identifier of the cloud provider region where the workspace group is deployed.
        firewallRanges:
          type: array
          description: List of CIDR IP ranges permitted to connect to workspaces in this group.
          items:
            type: string
        allowAllTraffic:
          type: boolean
          description: When true, all inbound traffic is allowed regardless of firewall ranges.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the workspace group was created.
        expiresAt:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp when the workspace group is scheduled to expire and be automatically terminated.
  responses:
    Unauthorized:
      description: The request did not include a valid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key generated from the SingleStore Cloud Portal. Pass the key as a Bearer token in the Authorization header of every request.
externalDocs:
  description: SingleStore Management API Documentation
  url: https://docs.singlestore.com/cloud/reference/management-api/