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. It supports operations for provisioning, updating, suspending, resuming, and deleting workspaces, as well as managing private connections, regions, organizations, jobs, files, secrets, and teams. Authentication uses HTTP Bearer tokens generated from the Cloud Portal, and all requests must be made over HTTPS. An OpenAPI specification is provided alongside the API to facilitate client SDK generation in multiple languages.
  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:
    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.
    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.
    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
    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
    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.
    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.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  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/