SingleStore Workspaces API

openapi: 3.2.0
info:
  title: SingleStore Management Workspaces 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: Workspaces
  description: Create, list, retrieve, update, suspend, resume, and delete workspaces within a workspace group. Workspaces are the compute resources that connect to a SingleStore database.
paths:
  /workspaces:
    get:
      operationId: listWorkspaces
      summary: List Workspaces
      description: Retrieves all workspaces accessible to the authenticated user, optionally filtered by workspace group ID. Returns workspace details including state, size, endpoint, and configuration.
      tags:
      - Workspaces
      parameters:
      - name: workspaceGroupID
        in: query
        description: Filter workspaces by the unique ID of the workspace group they belong to.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of workspaces returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkspace
      summary: Create a Workspace
      description: Creates a new workspace within an existing workspace group. The workspace provides compute capacity connected to the SingleStore database engine. Workspace size determines the number of vCPUs and memory allocated.
      tags:
      - Workspaces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceCreate'
      responses:
        '200':
          description: Workspace created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces/{workspaceID}:
    get:
      operationId: getWorkspace
      summary: Get a Workspace
      description: Retrieves detailed information about a specific workspace identified by its unique ID, including its current state, endpoint hostname, size, auto-suspend settings, and cache configuration.
      tags:
      - Workspaces
      parameters:
      - $ref: '#/components/parameters/workspaceIDPath'
      responses:
        '200':
          description: Workspace returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWorkspace
      summary: Update a Workspace
      description: Updates the configuration of an existing workspace, such as its auto-suspend settings, cache multiplier, size, or deployment type. Only the fields provided in the request body are modified.
      tags:
      - Workspaces
      parameters:
      - $ref: '#/components/parameters/workspaceIDPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceUpdate'
      responses:
        '200':
          description: Workspace updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: terminateWorkspace
      summary: Terminate a Workspace
      description: Terminates and permanently deletes the specified workspace. This operation is irreversible. The workspace must be in a non-transitional state before it can be terminated.
      tags:
      - Workspaces
      parameters:
      - $ref: '#/components/parameters/workspaceIDPath'
      - name: force
        in: query
        description: When set to true, forces termination of the workspace even if it is in an intermediate state.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Workspace terminated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /workspaces/{workspaceID}/suspend:
    post:
      operationId: suspendWorkspace
      summary: Suspend a Workspace
      description: Suspends an active workspace, pausing compute billing while retaining the workspace configuration and associated data. The workspace can be resumed at any time using the resume endpoint.
      tags:
      - Workspaces
      parameters:
      - $ref: '#/components/parameters/workspaceIDPath'
      responses:
        '200':
          description: Workspace suspension initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /workspaces/{workspaceID}/resume:
    post:
      operationId: resumeWorkspace
      summary: Resume a Workspace
      description: Resumes a suspended workspace, restoring compute capacity and making the workspace available for database connections. Optionally disables auto-suspend when resuming.
      tags:
      - Workspaces
      parameters:
      - $ref: '#/components/parameters/workspaceIDPath'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                disableAutoSuspend:
                  type: boolean
                  description: When true, disables the auto-suspend feature on the workspace after resuming.
      responses:
        '200':
          description: Workspace resume initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    WorkspaceDeleteResponse:
      type: object
      description: Response returned after initiating workspace termination.
      properties:
        workspaceID:
          type: string
          format: uuid
          description: Unique identifier of the workspace that was terminated.
    WorkspaceUpdate:
      type: object
      description: Request body for updating an existing workspace.
      properties:
        size:
          type: string
          description: Updated size designation for the workspace. Changing size causes a brief workspace restart.
        autoSuspend:
          $ref: '#/components/schemas/AutoSuspendConfig'
        cacheConfig:
          type: integer
          description: Updated cache multiplier. Valid values are 1, 2, or 4.
          enum:
          - 1
          - 2
          - 4
    Workspace:
      type: object
      description: A workspace provides compute capacity for running SQL queries against the SingleStore Helios database engine. It connects to a shared database within a workspace group and can be suspended and resumed independently.
      properties:
        workspaceID:
          type: string
          format: uuid
          description: Unique identifier of the workspace.
        workspaceGroupID:
          type: string
          format: uuid
          description: Unique identifier of the workspace group this workspace belongs to.
        name:
          type: string
          description: Human-readable name of the workspace.
        state:
          type: string
          description: Current lifecycle state of the workspace.
          enum:
          - PendingCreation
          - Transitioning
          - Active
          - Suspended
          - Resuming
          - Terminated
          - Failed
        size:
          type: string
          description: Workspace size designation (e.g., S-00, S-1, S-2) controlling the allocated vCPUs and memory.
        endpoint:
          type: string
          description: Hostname used for establishing database connections to this workspace.
        autoSuspend:
          $ref: '#/components/schemas/AutoSuspendConfig'
        cacheConfig:
          type: integer
          description: Cache multiplier applied to the workspace. Valid values are 1, 2, or 4.
          enum:
          - 1
          - 2
          - 4
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the workspace was created.
        expiresAt:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp when the workspace is scheduled to be automatically 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.
    WorkspaceCreate:
      type: object
      description: Request body for creating a new workspace.
      required:
      - workspaceGroupID
      - name
      - size
      properties:
        workspaceGroupID:
          type: string
          format: uuid
          description: Unique identifier of the workspace group to create the workspace in.
        name:
          type: string
          description: Human-readable name for the new workspace.
        size:
          type: string
          description: Size designation for the workspace controlling vCPUs and memory (e.g., S-00, S-1, S-2).
        autoSuspend:
          $ref: '#/components/schemas/AutoSuspendConfig'
        cacheConfig:
          type: integer
          description: Cache multiplier for the workspace. Valid values are 1, 2, or 4.
          enum:
          - 1
          - 2
          - 4
        expiresAt:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp after which the workspace will be automatically terminated.
    AutoSuspendConfig:
      type: object
      description: Configuration controlling automatic suspension of a workspace after a period of inactivity to reduce compute costs.
      properties:
        suspended:
          type: boolean
          description: When true, auto-suspend is enabled and the workspace will suspend after the specified idle interval.
        suspendAfterSeconds:
          type: integer
          description: Number of seconds of inactivity after which the workspace is automatically suspended.
          minimum: 60
  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:
    workspaceIDPath:
      name: workspaceID
      in: path
      required: true
      description: Unique identifier of the workspace.
      schema:
        type: string
        format: uuid
  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/