openapi: 3.1.0
info:
  title: SingleStore Data Files Workspaces 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: 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:
    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
    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.
    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.
    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
    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.
    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:
    workspaceIDPath:
      name: workspaceID
      in: path
      required: true
      description: Unique identifier of the workspace.
      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/