openapi: 3.1.0
info:
  title: SingleStore Data Files Secrets 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: Secrets
  description: Manage organization-level secrets that can be referenced securely in notebooks and jobs without exposing plaintext credentials.
paths:
  /secrets:
    get:
      operationId: listSecrets
      summary: List Secrets
      description: Retrieves all secrets defined in the current organization, optionally filtered by name. Secret values are not returned in list responses; only metadata such as name, ID, and timestamps are included.
      tags:
      - Secrets
      parameters:
      - name: name
        in: query
        description: Filter secrets by exact name match.
        schema:
          type: string
      responses:
        '200':
          description: List of secrets returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  secrets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Secret:
      type: object
      description: An organization-level secret that stores sensitive values such as API keys or passwords, which can be referenced in notebooks and jobs without exposing plaintext credentials.
      properties:
        secretID:
          type: string
          format: uuid
          description: Unique identifier of the secret.
        name:
          type: string
          description: Human-readable name used to reference the secret.
        createdBy:
          type: string
          description: Identifier of the user who created the secret.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the secret was created.
        lastUpdatedBy:
          type: string
          description: Identifier of the user who last updated the secret.
        lastUpdatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the secret was last updated.
    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'
  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/