SingleStore Jobs API

openapi: 3.2.0
info:
  title: SingleStore Management Jobs 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: Jobs
  description: Create, retrieve, list, and delete scheduled notebook jobs within SingleStore Helios. Jobs enable automated execution of notebooks on configurable schedules.
paths:
  /jobs:
    get:
      operationId: listJobs
      summary: List Jobs
      description: Retrieves all scheduled notebook jobs within the current organization, including job configuration, execution history metadata, and scheduling details.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/organizationIDQuery'
      responses:
        '200':
          description: List of jobs returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createJob
      summary: Create a Job
      description: Creates a new scheduled notebook job within the current organization. Jobs execute a specified notebook on a defined schedule or on demand, targeting a specific workspace and optional database.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreate'
      responses:
        '200':
          description: Job created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /jobs/{jobID}:
    get:
      operationId: getJob
      summary: Get a Job
      description: Retrieves detailed information about a specific scheduled notebook job identified by its unique job ID, including its schedule configuration, execution history, and current status.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobIDPath'
      responses:
        '200':
          description: Job returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteJob
      summary: Delete a Job
      description: Permanently deletes a scheduled notebook job identified by its unique job ID. Any currently executing job instances are not affected; only future executions are cancelled.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobIDPath'
      responses:
        '200':
          description: Job deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /jobs/{jobID}/executions:
    get:
      operationId: listJobExecutions
      summary: List Job Executions
      description: Retrieves the execution history for a specific job, with optional pagination by execution number range. Returns execution status, timing, and any associated snapshot notebook paths.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobIDPath'
      - name: start
        in: query
        description: The starting execution number for pagination.
        schema:
          type: integer
      - name: end
        in: query
        description: The ending execution number for pagination.
        schema:
          type: integer
      responses:
        '200':
          description: Job executions returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobExecution'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    JobExecutionConfig:
      type: object
      description: Configuration specifying the notebook to execute and runtime environment.
      required:
      - notebookPath
      properties:
        notebookPath:
          type: string
          description: Path to the notebook file within SingleStore Spaces to execute.
        runtimeName:
          type: string
          description: Name of the runtime environment to use for notebook execution.
        createSnapshot:
          type: boolean
          description: When true, a snapshot of the executed notebook with outputs is saved after each execution.
    JobSchedule:
      type: object
      description: Schedule configuration defining when and how often a job runs.
      properties:
        mode:
          type: string
          description: Scheduling mode controlling execution frequency. Use Once for a single immediate execution or Recurring for interval-based scheduling.
          enum:
          - Once
          - Recurring
        startAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp for when the job should first execute.
        executionIntervalInMinutes:
          type: integer
          description: Number of minutes between recurring executions. Required when mode is Recurring.
          minimum: 1
    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.
    JobExecution:
      type: object
      description: A single execution instance of a scheduled job, capturing its status and timing information.
      properties:
        executionID:
          type: string
          format: uuid
          description: Unique identifier of this job execution.
        jobID:
          type: string
          format: uuid
          description: Unique identifier of the parent job.
        status:
          type: string
          description: Current status of this execution.
          enum:
          - Queued
          - Running
          - Completed
          - Failed
          - Cancelled
        executionNumber:
          type: integer
          description: Sequential execution number for this job, starting at 1.
        scheduledStartTime:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this execution was scheduled to start.
        startedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this execution actually started.
        finishedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this execution completed or failed.
        snapshotNotebookPath:
          type: string
          description: Path to the snapshot notebook created after execution, if snapshot creation was enabled.
    JobParameter:
      type: object
      description: A parameter passed to a notebook at job execution time.
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Parameter name as referenced in the notebook.
        value:
          type: string
          description: Parameter value passed to the notebook.
        type:
          type: string
          description: Data type of the parameter value.
    JobTargetConfig:
      type: object
      description: Configuration specifying the workspace and database the notebook job should connect to.
      required:
      - targetID
      - targetType
      properties:
        targetID:
          type: string
          format: uuid
          description: Unique identifier of the workspace or workspace group to target.
        targetType:
          type: string
          description: Type of target resource. Use Workspace to target a specific workspace.
          enum:
          - Workspace
        databaseName:
          type: string
          description: Name of the database within the workspace to connect to during execution.
        resumeTarget:
          type: boolean
          description: When true, automatically resumes a suspended workspace before executing the notebook.
    JobCreate:
      type: object
      description: Request body for creating a new scheduled notebook job.
      required:
      - schedule
      - executionConfig
      - targetConfig
      properties:
        name:
          type: string
          description: Human-readable name for the job.
        description:
          type: string
          description: Optional description of the job's purpose.
        schedule:
          $ref: '#/components/schemas/JobSchedule'
        executionConfig:
          $ref: '#/components/schemas/JobExecutionConfig'
        targetConfig:
          $ref: '#/components/schemas/JobTargetConfig'
        parameters:
          type: array
          description: Optional parameters to pass to the notebook at execution time.
          items:
            $ref: '#/components/schemas/JobParameter'
    Job:
      type: object
      description: A scheduled notebook job that executes a specified notebook on a configurable schedule against a target workspace and database.
      properties:
        jobID:
          type: string
          format: uuid
          description: Unique identifier of the job.
        name:
          type: string
          description: Human-readable name of the job.
        description:
          type: string
          description: Optional description of the job's purpose.
        schedule:
          $ref: '#/components/schemas/JobSchedule'
        executionConfig:
          $ref: '#/components/schemas/JobExecutionConfig'
        targetConfig:
          $ref: '#/components/schemas/JobTargetConfig'
        completedExecutionsCount:
          type: integer
          description: Total number of completed executions for this job.
        enqueuedBy:
          type: string
          description: Identifier of the user who created or last triggered the job.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was created.
        terminatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was terminated, if applicable.
  parameters:
    jobIDPath:
      name: jobID
      in: path
      required: true
      description: Unique identifier of the job.
      schema:
        type: string
        format: uuid
    organizationIDQuery:
      name: organizationID
      in: query
      description: Filter results to a specific organization when the authenticated user belongs to multiple organizations.
      schema:
        type: string
        format: uuid
  responses:
    Unauthorized:
      description: The request did not include a valid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      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'
  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/