H2O.ai Scheduled Tasks API

openapi: 3.2.0
info:
  title: h2oGPTe REST Scheduled Tasks API
  description: '# Overview


    Users can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.'
  version: v1.0.0
servers:
- url: https://h2ogpte.genai.h2o.ai/api/v1
security:
- bearerAuth: []
tags:
- name: Scheduled Tasks
paths:
  /scheduled_tasks:
    post:
      operationId: create_scheduled_task
      summary: Create a scheduled task
      tags:
      - Scheduled Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledTaskCreateRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_scheduled_tasks
      summary: List scheduled tasks for the current user
      tags:
      - Scheduled Tasks
      parameters:
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      - name: name_filter
        in: query
        schema:
          type: string
      - name: status_filter
        in: query
        schema:
          type: string
      - name: collection_id
        in: query
        description: Only tasks bound to this collection (UUID). Mutually exclusive with has_collection.
        schema:
          type: string
      - name: has_collection
        in: query
        description: true = only collection-bound tasks; false = only tasks without a collection. Mutually exclusive with collection_id.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/summary:
    get:
      operationId: get_scheduled_task_summary
      summary: Aggregate stats for the current user's scheduled tasks
      tags:
      - Scheduled Tasks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/executions:
    get:
      operationId: list_all_user_scheduled_task_executions
      summary: List all executions across the current user's tasks
      tags:
      - Scheduled Tasks
      parameters:
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      - name: status_filter
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskExecutionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/batch_delete:
    post:
      operationId: delete_scheduled_tasks
      summary: Delete multiple scheduled tasks
      tags:
      - Scheduled Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledTaskBatchDeleteRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskBatchDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/{task_id}:
    get:
      operationId: get_scheduled_task
      summary: Get a scheduled task by id
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_scheduled_task
      summary: Update a scheduled task (partial)
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledTaskUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_scheduled_task
      summary: Delete a scheduled task
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/{task_id}/trigger:
    post:
      operationId: trigger_scheduled_task
      summary: Manually trigger a scheduled task
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskTriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/{task_id}/executions:
    get:
      operationId: list_scheduled_task_executions
      summary: List executions for a scheduled task
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskExecutionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks:
    get:
      operationId: list_scheduled_tasks_by_admin
      summary: List all scheduled tasks (admin only)
      tags:
      - Scheduled Tasks
      parameters:
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      - name: name_filter
        in: query
        schema:
          type: string
      - name: status_filter
        in: query
        schema:
          type: string
      - name: user_filter
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks/summary:
    get:
      operationId: get_scheduled_task_summary_by_admin
      summary: System-wide scheduled task summary (admin only)
      tags:
      - Scheduled Tasks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskAdminSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks/execution_stats:
    get:
      operationId: get_scheduled_task_execution_stats
      summary: Execution stats over an interval (admin only)
      tags:
      - Scheduled Tasks
      parameters:
      - name: interval
        in: query
        schema:
          type: string
        description: PostgreSQL interval, e.g. '7 days'. Default '7 days'.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskExecutionStats'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks/executions:
    get:
      operationId: list_scheduled_task_executions_by_admin
      summary: List executions across all users (admin only)
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: query
        schema:
          type: string
        description: Optional; if omitted, returns executions across all tasks.
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskExecutionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks/batch_delete:
    post:
      operationId: delete_scheduled_tasks_by_admin
      summary: Delete multiple scheduled tasks for any user (admin only)
      tags:
      - Scheduled Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledTaskBatchDeleteRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskBatchDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/scheduled_tasks/{task_id}:
    put:
      operationId: update_scheduled_task_by_admin
      summary: Update any scheduled task — status and metadata only (admin only)
      tags:
      - Scheduled Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledTaskAdminUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledTaskUpdateStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
components:
  schemas:
    ScheduledTaskExecutionStats:
      type: object
      properties:
        daily_executions:
          type: array
          items:
            type: object
            properties:
              day:
                type: string
              total:
                type: integer
              completed:
                type: integer
              failed:
                type: integer
        totals:
          type: object
          properties:
            total_executions:
              type: integer
            completed_executions:
              type: integer
            failed_executions:
              type: integer
            running_executions:
              type: integer
            total_tasks:
              type: integer
            active_tasks:
              type: integer
        top_tasks:
          type: array
          items:
            type: object
            properties:
              task_id:
                type: string
                format: uuid
              task_name:
                type: string
              username:
                type: string
              task_type:
                type: string
              execution_count:
                type: integer
              completed_count:
                type: integer
              failed_count:
                type: integer
    ScheduledTaskAdminSummary:
      type: object
      properties:
        total_tasks:
          type: integer
        active_tasks:
          type: integer
        currently_running_tasks:
          type: integer
        paused_tasks:
          type: integer
        completed_tasks:
          type: integer
        expired_tasks:
          type: integer
        recurring_tasks:
          type: integer
        one_time_tasks:
          type: integer
        chat_completion_tasks:
          type: integer
        agent_tasks:
          type: integer
        total_executions:
          type: integer
        tasks_executing_today:
          type: integer
        unique_users:
          type: integer
        failed_executions_today:
          type: integer
        running_executions:
          type: integer
    ScheduledTaskExecution:
      type: object
      properties:
        id:
          type: string
          format: uuid
        scheduled_task_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - running
          - completed
          - failed
          - cancelled
        trigger_source:
          type:
          - string
          - 'null'
          enum:
          - scheduled
          - manual
        task_name:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        chat_session_id:
          type:
          - string
          - 'null'
          format: uuid
        result_summary:
          type:
          - string
          - 'null'
        error_message:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
    ScheduledTaskTriggerResponse:
      type: object
      properties:
        execution_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        status:
          type: string
    ScheduledTask:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        username:
          type: string
        name:
          type: string
        description:
          type: string
        schedule_type:
          type: string
          enum:
          - once
          - recurring
          - interval
        schedule_expression:
          type: string
        task_type:
          type: string
          enum:
          - chat_completion
          - agent_task
        task_config:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
          - active
          - paused
          - completed
          - expired
        execution_status:
          type: string
          description: 'Runtime execution state: idle or running.'
        last_execution_at:
          type:
          - string
          - 'null'
          format: date-time
        next_execution_at:
          type:
          - string
          - 'null'
          format: date-time
        execution_count:
          type: integer
        max_executions:
          type:
          - integer
          - 'null'
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_owner:
          type: boolean
        notification_email:
          type: string
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    ScheduledTaskDeleteResponse:
      type: object
      properties:
        status:
          type: string
    ScheduledTaskUpdateRequest:
      type: object
      description: 'Partial update. Omit a field to leave it unchanged. To CLEAR a nullable field, use the sentinel: max_executions = -1 clears it; expires_at = 1970-01-01T00:00:00Z clears it. To pause/resume, set status to "paused"/"active".

        '
      properties:
        name:
          type: string
        description:
          type: string
        schedule_type:
          type: string
          enum:
          - once
          - recurring
          - interval
        schedule_expression:
          type: string
        task_type:
          type: string
          enum:
          - chat_completion
          - agent_task
        task_config:
          type: object
          additionalProperties: true
        task_config_patch:
          type: object
          additionalProperties: true
          description: 'Partial task_config update. Top-level keys are merged into the stored task_config; a key whose value is JSON null is REMOVED (e.g. {"collection_id": null} unbinds the collection). Nested objects are replaced whole, not deep-merged. Mutually exclusive with task_config. The merged result must keep a non-empty ''message''.

            '
        status:
          type: string
          enum:
          - active
          - paused
          - completed
          - expired
        max_executions:
          type:
          - integer
          - 'null'
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        notification_email:
          type: string
    ScheduledTaskCreateRequest:
      type: object
      required:
      - name
      - schedule_type
      - schedule_expression
      - task_type
      - task_config
      properties:
        name:
          type: string
        description:
          type: string
        schedule_type:
          type: string
          enum:
          - once
          - recurring
          - interval
        schedule_expression:
          type: string
          description: ISO-8601 datetime for once, 5-field cron for recurring, "N minutes"/"N hours" for interval.
        task_type:
          type: string
          enum:
          - chat_completion
          - agent_task
        task_config:
          type: object
          additionalProperties: true
          description: Must contain a non-empty "message" key (the question/prompt). May include "timezone", "collection_id", "llm_args".
        max_executions:
          type:
          - integer
          - 'null'
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        notification_email:
          type: string
    ScheduledTaskUpdateStatusResponse:
      type: object
      properties:
        status:
          type: string
    ScheduledTaskBatchDeleteResponse:
      type: object
      properties:
        status:
          type: string
        count:
          type: integer
    ScheduledTaskExecutionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledTaskExecution'
        total:
          type: integer
    ScheduledTaskAdminUpdateRequest:
      type: object
      description: 'Admin partial update — status and metadata only. max_executions and expires_at are intentionally NOT settable here (the admin SQL does not honor the clear-sentinels), matching the UI''s admin update which only changes status.

        '
      properties:
        name:
          type: string
        description:
          type: string
        schedule_type:
          type: string
          enum:
          - once
          - recurring
          - interval
        schedule_expression:
          type: string
        task_type:
          type: string
          enum:
          - chat_completion
          - agent_task
        task_config:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
          - active
          - paused
          - completed
          - expired
        notification_email:
          type: string
    ScheduledTaskList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledTask'
        total:
          type: integer
    ScheduledTaskBatchDeleteRequest:
      type: object
      required:
      - task_ids
      properties:
        task_ids:
          type: array
          items:
            type: string
            format: uuid
    ScheduledTaskSummary:
      type: object
      properties:
        total_tasks:
          type: integer
        active_tasks:
          type: integer
        currently_running_tasks:
          type: integer
        paused_tasks:
          type: integer
        completed_tasks:
          type: integer
        expired_tasks:
          type: integer
        recurring_tasks:
          type: integer
        one_time_tasks:
          type: integer
        chat_completion_tasks:
          type: integer
        agent_tasks:
          type: integer
        total_executions:
          type: integer
        tasks_executing_today:
          type: integer
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unexpected:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe