H2O.ai System API

openapi: 3.2.0
info:
  title: h2oGPTe REST System 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: System
paths:
  /admin/user_limits/export:
    get:
      tags:
      - System
      summary: Export user limits as CSV
      description: Generates and streams a CSV of user limits data. Admin only.
      operationId: download_user_limits_export
      parameters:
      - name: search
        in: query
        description: Search string to filter users by username or email.
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filter by limit status. One of all, within_limit, approaching, blocked.
        required: false
        schema:
          type: string
          default: all
      - name: user_ids
        in: query
        description: Comma-separated user IDs to export. When set, search and filter are ignored.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: CSV file download
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Admin access required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointError'
        default:
          $ref: '#/components/responses/Unexpected'
  /system/h2ogpt_info:
    get:
      operationId: get_h2ogpt_system_info
      summary: Gets H2OGPT system information
      description: Gets H2OGPT system information.
      tags:
      - System
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/H2OGPTSystemInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /scheduled_tasks/generate_spec:
    post:
      operationId: generate_scheduled_task_spec
      summary: Generate a scheduled task spec from a prompt
      description: 'Uses an LLM with guided JSON to generate a scheduled task configuration

        from a natural language description. The returned spec can be used directly

        with the create_scheduled_task RPC.'
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: Natural language description of the desired scheduled task.
                llm:
                  type: string
                  description: Optional LLM model override for generation.
                timezone:
                  type: string
                  description: 'Optional IANA timezone string (e.g. "America/New_York") used to compute

                    today''s local date for relative schedule expressions. Defaults to UTC.

                    '
                use_agent:
                  type: boolean
                  description: 'When true, signals to the LLM that the user has agent mode enabled in

                    their chat so it should prefer task_type=agent_task unless the prompt

                    clearly describes a plain chat-completion task. Does not force the

                    generated task_type.

                    '
        required: true
      responses:
        '200':
          description: Generated scheduled task configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    type: object
                    description: The generated scheduled task spec.
                  passed:
                    type: boolean
                    description: 'Whether the user prompt was minimally sufficient to create the task.

                      Callers MUST NOT create the task when passed is false; only show

                      `response` to the user.

                      '
                  response:
                    type: string
                    description: 'When passed=false, a clarifying question describing what info is missing.

                      When passed=true, a human-language confirmation of what was scheduled,

                      including any defaults the LLM inferred.

                      '
                  llm_used:
                    type: string
                    description: The actual model that generated the spec.
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events stream when `Accept: text/event-stream` is requested.

                  Three event types are emitted:

                  - `progress` — `{"chars": <number>}` incremental character count from the LLM stream.

                  - `done` — same JSON payload as the `application/json` 200 response.

                  - `error` — `{"message": "<string>"}` on generation failure.

                  '
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
components:
  schemas:
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    H2OGPTSystemInfo:
      required:
      - timestamp
      - uptime_seconds
      - hostname
      - os_name
      - os_version
      - kernel_version
      - cpu_count_physical
      - cpu_count_logical
      - cpu_percent_per_cpu
      - cpu_freq_current
      - cpu_freq_min
      - cpu_freq_max
      - load_avg_1min
      - load_avg_5min
      - load_avg_15min
      - memory_total
      - memory_available
      - memory_used
      - memory_percent
      - swap_total
      - swap_used
      - swap_percent
      - disk_partitions
      - disk_usage
      - disk_io_counters
      - network_interfaces
      - network_io_counters
      - network_connections_count
      - gpus
      - process_count
      - top_processes_cpu
      - top_processes_memory
      type: object
      properties:
        timestamp:
          type: string
        uptime_seconds:
          type: number
        hostname:
          type: string
        os_name:
          type: string
        os_version:
          type: string
        kernel_version:
          type: string
        cpu_count_physical:
          type: integer
        cpu_count_logical:
          type: integer
        cpu_percent_per_cpu:
          type: array
          items:
            type: number
        cpu_freq_current:
          type: number
        cpu_freq_min:
          type: number
        cpu_freq_max:
          type: number
        cpu_temperature:
          type: number
        load_avg_1min:
          type: number
        load_avg_5min:
          type: number
        load_avg_15min:
          type: number
        memory_total:
          type: integer
        memory_available:
          type: integer
        memory_used:
          type: integer
        memory_percent:
          type: number
        swap_total:
          type: integer
        swap_used:
          type: integer
        swap_percent:
          type: number
        disk_partitions:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
        disk_usage:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        disk_io_counters:
          type: object
          additionalProperties:
            type: number
        network_interfaces:
          type: array
          items:
            type: string
        network_io_counters:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        network_connections_count:
          type: integer
        gpus:
          type: array
          items:
            $ref: '#/components/schemas/H2OGPTGPUInfo'
        process_count:
          type: integer
        top_processes_cpu:
          type: array
          items:
            type: object
        top_processes_memory:
          type: array
          items:
            type: object
    H2OGPTGPUInfo:
      required:
      - name
      type: object
      properties:
        name:
          type: string
        temperature:
          type: number
        utilization:
          type: number
        memory_total:
          type: integer
        memory_used:
          type: integer
        power_usage:
          type: number
        fan_speed:
          type: integer
  responses:
    Unexpected:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe