openapi: 3.1.0
info:
  title: Quickwit REST Cluster Indexes API
  description: 'The Quickwit REST API provides endpoints for indexing NDJSON documents, executing full-text and aggregation search queries, managing indexes and data sources, streaming field values, deleting documents by query, and monitoring cluster health. Quickwit is a cloud-native search engine for log management and full-text search at petabyte scale.

    '
  version: 0.8.2
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Quickwit, Inc.
    email: hello@quickwit.io
  x-api-evangelist-rating:
    designScore: 70
    reliability: 80
    documentation: 75
servers:
- url: http://localhost:7280/api/v1
  description: Local Quickwit node
tags:
- name: Indexes
  description: Create, update, retrieve, and manage search indexes
paths:
  /indexes:
    get:
      operationId: listIndexes
      summary: List all indexes
      description: Returns metadata for all indexes in the cluster.
      tags:
      - Indexes
      responses:
        '200':
          description: List of index metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IndexMetadata'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createIndex
      summary: Create an index
      description: Creates a new search index with the provided configuration.
      tags:
      - Indexes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexConfig'
          application/yaml:
            schema:
              $ref: '#/components/schemas/IndexConfig'
      responses:
        '200':
          description: Index created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Index already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          $ref: '#/components/responses/InternalError'
  /indexes/{index_id}:
    get:
      operationId: getIndex
      summary: Get index metadata
      description: Returns the metadata for a specific index.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      responses:
        '200':
          description: Index metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexMetadata'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateIndex
      summary: Update an index
      description: Updates an existing index configuration. Optionally creates the index if it does not exist.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      - name: create
        in: query
        description: Create the index if it does not exist
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexConfig'
          application/yaml:
            schema:
              $ref: '#/components/schemas/IndexConfig'
      responses:
        '200':
          description: Index updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteIndex
      summary: Delete an index
      description: Deletes an index and returns the metadata of all deleted splits.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      responses:
        '200':
          description: Index deleted, returns deleted splits
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SplitMetadata'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /indexes/{index_id}/describe:
    get:
      operationId: describeIndex
      summary: Describe an index
      description: Returns statistics and metadata about the index including document counts and size.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      responses:
        '200':
          description: Index description with statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexDescription'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /indexes/{index_id}/clear:
    put:
      operationId: clearIndex
      summary: Clear an index
      description: Removes all documents from the index while keeping the index configuration.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      responses:
        '200':
          description: Index cleared successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /indexes/{index_id}/splits:
    get:
      operationId: listSplits
      summary: List splits
      description: Returns the list of splits for a given index with optional filtering.
      tags:
      - Indexes
      parameters:
      - $ref: '#/components/parameters/indexId'
      - name: offset
        in: query
        description: Number of splits to skip
        required: false
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        description: Maximum number of splits to return
        required: false
        schema:
          type: integer
          minimum: 1
      - name: split_states
        in: query
        description: Filter by split state (comma-separated)
        required: false
        schema:
          type: string
      - name: start_timestamp
        in: query
        description: Minimum timestamp filter in seconds
        required: false
        schema:
          type: integer
          format: int64
      - name: end_timestamp
        in: query
        description: Maximum timestamp filter in seconds
        required: false
        schema:
          type: integer
          format: int64
      - name: end_create_timestamp
        in: query
        description: Maximum creation date filter
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: List of splits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitList'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    IndexMetadata:
      type: object
      properties:
        version:
          type: string
        index_uid:
          type: string
          description: Unique index ID including generation
        index_config:
          $ref: '#/components/schemas/IndexConfig'
        checkpoint:
          type: object
          description: Current indexing checkpoint per source
        create_timestamp:
          type: integer
          format: int64
          description: Unix timestamp when the index was created
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceConfig'
    IndexDescription:
      type: object
      properties:
        index_id:
          type: string
        index_uri:
          type: string
        num_published_splits:
          type: integer
        size_published_splits:
          type: integer
          format: int64
          description: Size in bytes of published splits
        num_published_docs:
          type: integer
          format: int64
        size_published_docs_uncompressed:
          type: integer
          format: int64
          description: Uncompressed size in bytes of indexed documents
        timestamp_field_name:
          type: string
        min_timestamp:
          type: integer
          format: int64
        max_timestamp:
          type: integer
          format: int64
    IndexConfig:
      type: object
      required:
      - version
      - index_id
      - doc_mapping
      properties:
        version:
          type: string
          description: Configuration format version
          example: '0.8'
        index_id:
          type: string
          description: Unique index identifier
          example: my-log-index
        index_uri:
          type: string
          description: Storage URI (defaults to configured storage)
          example: s3://my-bucket/my-index
        doc_mapping:
          $ref: '#/components/schemas/DocMapping'
        indexing_settings:
          $ref: '#/components/schemas/IndexingSettings'
        search_settings:
          $ref: '#/components/schemas/SearchSettings'
        retention:
          $ref: '#/components/schemas/RetentionPolicy'
    RetentionPolicy:
      type: object
      properties:
        period:
          type: string
          description: Retention period (e.g. "90 days")
        schedule:
          type: string
          description: Cron schedule for retention enforcement
    SplitList:
      type: object
      properties:
        offset:
          type: integer
        size:
          type: integer
        splits:
          type: array
          items:
            $ref: '#/components/schemas/SplitMetadata'
    SearchSettings:
      type: object
      properties:
        default_search_fields:
          type: array
          items:
            type: string
          description: Fields searched when no field is specified in the query
    IndexingSettings:
      type: object
      properties:
        commit_timeout_secs:
          type: integer
          description: Maximum time before committing a split (seconds)
        split_num_docs_target:
          type: integer
          description: Target number of docs per split
        merge_policy:
          type: object
          description: Merge policy configuration
        resources:
          type: object
          description: Resource limits for indexing
    SourceConfig:
      type: object
      required:
      - version
      - source_id
      - source_type
      - params
      properties:
        version:
          type: string
          description: Configuration format version
        source_id:
          type: string
          description: Unique source identifier
          example: my-kafka-source
        source_type:
          type: string
          enum:
          - kafka
          - kinesis
          - pulsar
          - file
          - vec
          - void
          - ingest-v2
          description: Type of data source
        num_pipelines:
          type: integer
          minimum: 1
          default: 1
          description: Number of indexing pipelines per node
        transform:
          type: object
          nullable: true
          description: VRL transformation applied to documents before indexing
          properties:
            vrl_script:
              type: string
              description: VRL script content
            timezone:
              type: string
              default: UTC
        params:
          type: object
          description: Source-specific parameters
          additionalProperties: true
    ApiError:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message
      example:
        message: Index 'my-index' not found
    DocMapping:
      type: object
      properties:
        field_mappings:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
                enum:
                - text
                - u64
                - i64
                - f64
                - bool
                - datetime
                - json
                - bytes
                - ip
              fast:
                type: boolean
              indexed:
                type: boolean
              stored:
                type: boolean
        timestamp_field:
          type: string
          description: Field used as the document timestamp
        tag_fields:
          type: array
          items:
            type: string
        store_source:
          type: boolean
          description: Whether to store the original source document
        dynamic_mapping:
          type: object
          description: Configuration for dynamic field mapping
    SplitMetadata:
      type: object
      properties:
        split_id:
          type: string
        index_uid:
          type: string
        split_state:
          type: string
          enum:
          - Staged
          - Published
          - MarkedForDeletion
        num_docs:
          type: integer
        size_in_bytes:
          type: integer
          format: int64
        create_timestamp:
          type: integer
          format: int64
        time_range:
          type: object
          properties:
            start:
              type: integer
              format: int64
            end:
              type: integer
              format: int64
  responses:
    BadRequest:
      description: Bad request - invalid parameters or body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  parameters:
    indexId:
      name: index_id
      in: path
      description: The index identifier
      required: true
      schema:
        type: string
      example: my-index