Typesense Configuration Changes API

openapi: 3.2.0
info:
  title: Typesense Cloud Management Configuration Changes API
  description: The Typesense Cloud Management API provides endpoints for provisioning and managing Typesense Cloud clusters programmatically. It supports creating, updating, and deleting clusters, managing cluster configuration parameters, generating API keys, and applying configuration changes. This API enables infrastructure automation for teams running Typesense on the managed cloud platform, with authentication handled through cloud management API keys.
  version: '1'
  contact:
    name: Typesense Support
    url: https://typesense.org/support
  termsOfService: https://typesense.org/terms
servers:
- url: https://cloud.typesense.org/api/v1
  description: Typesense Cloud API
security:
- cloudApiKey: []
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:
    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.
    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
  parameters:
    changeId:
      name: changeId
      in: path
      required: true
      description: Unique identifier of the configuration change.
      schema:
        type: string
    clusterId:
      name: clusterId
      in: path
      required: true
      description: Unique identifier of the cluster.
      schema:
        type: string
  securitySchemes:
    cloudApiKey:
      type: apiKey
      in: header
      name: X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY
      description: Cloud management API key for authenticating requests to the Typesense Cloud Management API.
externalDocs:
  description: Typesense Cloud Management API Documentation
  url: https://typesense.org/docs/cloud-management-api/v1/cluster-management.html