SingleStore Files API

openapi: 3.2.0
info:
  title: SingleStore Management Files 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: Files
  description: Upload, download, list, and delete files in the personal, shared, or models space within SingleStore Helios Spaces (stage storage).
paths:
  /stage/{deploymentID}/fs/{stagePath}:
    get:
      operationId: getStageFile
      summary: Get or List Stage File
      description: Retrieves a file from the stage filesystem at the specified path, or lists directory contents when the path points to a directory. Use the metadata query parameter to return object metadata instead of file content.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/deploymentIDPath'
      - $ref: '#/components/parameters/stagePathPath'
      - name: metadata
        in: query
        description: When set to 1, returns file metadata (size, type, modified date) instead of file content.
        schema:
          type: integer
          enum:
          - 1
      responses:
        '200':
          description: File content or metadata returned successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: uploadStageFile
      summary: Upload a Stage File
      description: Uploads a file to the stage filesystem at the specified path, creating parent directories as needed. Existing files at the same path are overwritten.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/deploymentIDPath'
      - $ref: '#/components/parameters/stagePathPath'
      - name: isFile
        in: query
        description: When set to false, creates a directory instead of uploading a file.
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File uploaded successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: renameStageFile
      summary: Rename or Move a Stage File
      description: Renames or moves a file or directory within the stage filesystem from the specified old path to a new path provided in the request body.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/deploymentIDPath'
      - $ref: '#/components/parameters/stagePathPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newPath
              properties:
                newPath:
                  type: string
                  description: The new path for the file or directory within the stage filesystem.
      responses:
        '200':
          description: File renamed or moved successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteStageFile
      summary: Delete a Stage File
      description: Deletes a file or directory from the stage filesystem at the specified path. Directory deletion removes all contained files and subdirectories recursively.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/deploymentIDPath'
      - $ref: '#/components/parameters/stagePathPath'
      responses:
        '200':
          description: File deleted successfully.
        '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.
  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'
  parameters:
    stagePathPath:
      name: stagePath
      in: path
      required: true
      description: File or directory path within the stage filesystem.
      schema:
        type: string
    deploymentIDPath:
      name: deploymentID
      in: path
      required: true
      description: Unique deployment identifier associated with a workspace group, used to address the stage filesystem.
      schema:
        type: string
  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/