Typesense Configuration Changes API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events Configuration Changes API
  description: The Typesense Analytics API allows developers to track and analyze search behavior by recording click, conversion, and visit events. It provides endpoints for creating analytics rules, logging events with metadata tags, and retrieving popular queries and queries with no results. This data can be used to improve search relevance through query suggestions, curations, and understanding user search patterns.
  version: '30.1'
  contact:
    name: Typesense Support
    url: https://typesense.org/support
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
  termsOfService: https://typesense.org/terms
servers:
- url: '{protocol}://{hostname}:{port}'
  description: Typesense Server
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    hostname:
      default: localhost
    port:
      default: '8108'
security:
- api_key_header: []
tags:
- name: Configuration Changes
  description: Schedule, retrieve, list, and cancel configuration changes to running clusters such as memory upgrades, version changes, and HA toggles.
paths:
  /clusters/{clusterId}/configuration-changes:
    parameters:
    - $ref: '#/components/parameters/clusterId'
    post:
      operationId: createConfigurationChange
      summary: Schedule A Configuration Change
      description: Schedules a configuration change for a cluster such as upgrading memory, changing vCPU allocation, upgrading Typesense server version, or enabling/disabling high availability. Changes are applied at the specified time.
      tags:
      - Configuration Changes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationChangeCreateSchema'
      responses:
        '201':
          description: Configuration change scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationChange'
        '400':
          description: Bad request - invalid configuration
        '401':
          description: Unauthorized
        '404':
          description: Cluster not found
    get:
      operationId: listConfigurationChanges
      summary: List Configuration Changes
      description: Retrieves all configuration changes for a cluster, including pending, applied, and canceled changes.
      tags:
      - Configuration Changes
      parameters:
      - name: per_page
        in: query
        description: Number of results per page.
        schema:
          type: integer
      responses:
        '200':
          description: List of configuration changes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConfigurationChange'
        '401':
          description: Unauthorized
        '404':
          description: Cluster not found
  /clusters/{clusterId}/configuration-changes/{changeId}:
    parameters:
    - $ref: '#/components/parameters/clusterId'
    - $ref: '#/components/parameters/changeId'
    get:
      operationId: getConfigurationChange
      summary: Retrieve A Configuration Change
      description: Retrieves details of a specific configuration change by ID.
      tags:
      - Configuration Changes
      responses:
        '200':
          description: Configuration change details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationChange'
        '401':
          description: Unauthorized
        '404':
          description: Configuration change or cluster not found
    patch:
      operationId: updateConfigurationChange
      summary: Cancel A Configuration Change
      description: Updates a configuration change, typically to cancel a pending change by setting its status to canceled.
      tags:
      - Configuration Changes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: Set to canceled to cancel the pending change.
                  enum:
                  - canceled
      responses:
        '200':
          description: Configuration change updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationChange'
        '400':
          description: Bad request - change cannot be canceled
        '401':
          description: Unauthorized
        '404':
          description: Configuration change or cluster not found
components:
  schemas:
    ConfigurationChangeCreateSchema:
      type: object
      properties:
        new_memory:
          type: string
          description: New memory allocation, such as 1_gb, 2_gb, etc.
        new_vcpu:
          type: string
          description: New vCPU configuration.
        new_gpu:
          type: boolean
          description: Whether to enable or disable GPU.
        new_high_performance_disk:
          type: string
          description: New high-performance disk configuration.
        new_typesense_server_version:
          type: string
          description: Typesense Server version to upgrade to.
        new_high_availability:
          type: string
          description: Enable or disable high availability.
          enum:
          - 'yes'
          - 'no'
        perform_change_at:
          type: integer
          format: int64
          description: Unix timestamp for when the change should be applied.
        notification_email_addresses:
          type: array
          description: Email addresses to notify about the configuration change.
          items:
            type: string
    ConfigurationChange:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the configuration change.
        status:
          type: string
          description: Current status of the change.
          enum:
          - pending
          - in_progress
          - completed
          - canceled
          - failed
        new_memory:
          type: string
        new_vcpu:
          type: string
        new_typesense_server_version:
          type: string
        new_high_availability:
          type: string
        perform_change_at:
          type: integer
          format: int64
          description: Scheduled time for the change.
        created_at:
          type: string
          format: date-time
          description: When the change was created.
  parameters:
    clusterId:
      name: clusterId
      in: path
      required: true
      description: Unique identifier of the cluster.
      schema:
        type: string
    changeId:
      name: changeId
      in: path
      required: true
      description: Unique identifier of the configuration change.
      schema:
        type: string
  securitySchemes:
    api_key_header:
      type: apiKey
      in: header
      name: X-TYPESENSE-API-KEY
      description: API key for authenticating requests to the Typesense server.
externalDocs:
  description: Typesense Analytics Documentation
  url: https://typesense.org/docs/30.1/api/analytics-query-suggestions.html