openapi: 3.1.0
info:
  title: SingleStore Data Files WorkspaceGroups API
  description: The SingleStore Data API enables developers to execute SQL statements against a SingleStore Helios database over standard HTTP connections without requiring a native database driver or MySQL-compatible client. It supports all SQL statements available through a direct database connection, returning results as JSON-encoded responses using standard HTTP methods and response codes. The API exposes endpoints for executing DDL and DML statements via /api/v2/exec and returning query result sets via /api/v2/query/rows and /api/v2/query/tuples. Authentication is handled using HTTP Basic or Bearer Authentication over HTTPS. The API supports up to 192 parallel requests per aggregator, making it suitable for serverless architectures and custom application integrations.
  version: v2
  contact:
    name: SingleStore Support
    url: https://support.singlestore.com
  termsOfService: https://www.singlestore.com/cloud-terms-and-conditions/
servers:
- url: https://{workspaceHost}
  description: SingleStore Helios workspace endpoint. Replace workspaceHost with the hostname of the target workspace obtained from the Cloud Portal or Management API.
  variables:
    workspaceHost:
      default: your-workspace.singlestore.com
      description: Hostname of the SingleStore Helios workspace to query. Obtain this value from the workspace endpoint field in the Cloud Portal or via the Management API.
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: WorkspaceGroups
  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:
      - WorkspaceGroups
      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:
      - WorkspaceGroups
      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:
      - WorkspaceGroups
      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:
      - WorkspaceGroups
      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:
      - WorkspaceGroups
      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:
  schemas:
    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.
    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.
    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.
    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.
  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'
  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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using SingleStore database credentials. Provide the username and password as a Base-64 encoded username:password string in the Authorization header.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using a JWT token obtained from the SingleStore Cloud Portal.
externalDocs:
  description: SingleStore Data API Documentation
  url: https://docs.singlestore.com/cloud/reference/data-api/