openapi: 3.1.0
info:
  title: Quickwit REST 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: Search
    description: Query documents across indexes using full-text and aggregation queries
  - name: Ingest
    description: Add documents to indexes via NDJSON format
  - name: Indexes
    description: Create, update, retrieve, and manage search indexes
  - name: Sources
    description: Configure data sources such as Kafka, Kinesis, and Pulsar
  - name: Delete Tasks
    description: Remove documents matching queries from indexes
  - name: Cluster
    description: Monitor cluster state and node health
  - name: Index Templates
    description: Manage index templates for automatic index creation

paths:
  /health/livez:
    get:
      operationId: livenessCheck
      summary: Liveness check
      description: Returns 200 if the node is alive.
      tags:
        - Cluster
      responses:
        '200':
          description: Node is alive

  /health/readyz:
    get:
      operationId: readinessCheck
      summary: Readiness check
      description: Returns 200 if the node is ready to serve requests.
      tags:
        - Cluster
      responses:
        '200':
          description: Node is ready

  /cluster:
    get:
      operationId: getCluster
      summary: Get cluster state
      description: Returns the current state of the Quickwit cluster including all node information.
      tags:
        - Cluster
      parameters:
        - name: format
          in: query
          description: Output format
          required: false
          schema:
            type: string
            enum: [json, pretty_json]
            default: pretty_json
      responses:
        '200':
          description: Cluster state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterState'
        '500':
          $ref: '#/components/responses/InternalError'

  /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'

  /indexes/{index_id}/search:
    get:
      operationId: searchIndexGet
      summary: Search an index (GET)
      description: Executes a search query against a specific index using GET parameters.
      tags:
        - Search
      parameters:
        - $ref: '#/components/parameters/indexId'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/startTimestamp'
        - $ref: '#/components/parameters/endTimestamp'
        - $ref: '#/components/parameters/startOffset'
        - $ref: '#/components/parameters/maxHits'
        - $ref: '#/components/parameters/searchField'
        - $ref: '#/components/parameters/snippetFields'
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      operationId: searchIndexPost
      summary: Search an index (POST)
      description: Executes a search query against a specific index using a JSON request body.
      tags:
        - Search
      parameters:
        - $ref: '#/components/parameters/indexId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/ingest:
    post:
      operationId: ingestDocuments
      summary: Ingest documents
      description: >
        Ingests NDJSON documents into an index. Each line in the request body
        must be a valid JSON object. The commit parameter controls when the
        documents become searchable.
      tags:
        - Ingest
      parameters:
        - $ref: '#/components/parameters/indexId'
        - name: commit
          in: query
          description: >
            Controls when documents become searchable.
            'auto' lets Quickwit decide, 'wait_for' waits for next commit,
            'force' triggers an immediate commit.
          required: false
          schema:
            type: string
            enum: [auto, wait_for, force]
            default: auto
        - name: detailed_response
          in: query
          description: Include parse_failures in the response
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/x-ndjson:
            schema:
              type: string
              description: NDJSON formatted documents, one per line
            example: |
              {"message": "log line 1", "timestamp": 1700000000}
              {"message": "log line 2", "timestamp": 1700000001}
      responses:
        '200':
          description: Documents ingested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/delete-tasks:
    get:
      operationId: listDeleteTasks
      summary: List delete tasks
      description: Returns all delete tasks for a given index.
      tags:
        - Delete Tasks
      parameters:
        - $ref: '#/components/parameters/indexId'
      responses:
        '200':
          description: List of delete tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeleteTask'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      operationId: createDeleteTask
      summary: Create a delete task
      description: Creates a task to delete all documents matching a query from an index.
      tags:
        - Delete Tasks
      parameters:
        - $ref: '#/components/parameters/indexId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteQuery'
      responses:
        '200':
          description: Delete task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTask'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/sources:
    post:
      operationId: createSource
      summary: Create a source
      description: Creates a new data source for an index.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/indexId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceConfig'
      responses:
        '200':
          description: Source created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/sources/{source_id}:
    put:
      operationId: updateSource
      summary: Update a source
      description: Updates an existing data source configuration.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/indexId'
        - $ref: '#/components/parameters/sourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceConfig'
      responses:
        '200':
          description: Source updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    delete:
      operationId: deleteSource
      summary: Delete a source
      description: Deletes a data source from an index.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/indexId'
        - $ref: '#/components/parameters/sourceId'
      responses:
        '200':
          description: Source deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/sources/{source_id}/toggle:
    put:
      operationId: toggleSource
      summary: Toggle a source
      description: Enables or disables a data source.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/indexId'
        - $ref: '#/components/parameters/sourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enable
              properties:
                enable:
                  type: boolean
                  description: Set to true to enable, false to disable
      responses:
        '200':
          description: Source toggled successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /indexes/{index_id}/sources/{source_id}/reset-checkpoint:
    put:
      operationId: resetSourceCheckpoint
      summary: Reset source checkpoint
      description: Resets the checkpoint for a data source, causing it to re-read from the beginning.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/indexId'
        - $ref: '#/components/parameters/sourceId'
      responses:
        '200':
          description: Source checkpoint reset successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /templates:
    get:
      operationId: listIndexTemplates
      summary: List index templates
      description: Returns all index templates.
      tags:
        - Index Templates
      responses:
        '200':
          description: List of index templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IndexTemplate'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      operationId: createIndexTemplate
      summary: Create an index template
      description: Creates a new index template used to auto-configure new indexes.
      tags:
        - Index Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexTemplate'
          application/yaml:
            schema:
              $ref: '#/components/schemas/IndexTemplate'
      responses:
        '200':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /templates/{template_id}:
    get:
      operationId: getIndexTemplate
      summary: Get an index template
      description: Returns a specific index template.
      tags:
        - Index Templates
      parameters:
        - $ref: '#/components/parameters/templateId'
      responses:
        '200':
          description: Index template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexTemplate'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    put:
      operationId: updateIndexTemplate
      summary: Update an index template
      description: Updates an existing index template.
      tags:
        - Index Templates
      parameters:
        - $ref: '#/components/parameters/templateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexTemplate'
          application/yaml:
            schema:
              $ref: '#/components/schemas/IndexTemplate'
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

    delete:
      operationId: deleteIndexTemplate
      summary: Delete an index template
      description: Deletes an index template.
      tags:
        - Index Templates
      parameters:
        - $ref: '#/components/parameters/templateId'
      responses:
        '200':
          description: Template deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  parameters:
    indexId:
      name: index_id
      in: path
      description: The index identifier
      required: true
      schema:
        type: string
      example: my-index

    sourceId:
      name: source_id
      in: path
      description: The source identifier
      required: true
      schema:
        type: string
      example: my-kafka-source

    templateId:
      name: template_id
      in: path
      description: The index template identifier
      required: true
      schema:
        type: string
      example: my-template

    query:
      name: query
      in: query
      description: Full-text search query string
      required: true
      schema:
        type: string
      example: "error AND severity:high"

    startTimestamp:
      name: start_timestamp
      in: query
      description: Minimum timestamp filter in seconds (inclusive)
      required: false
      schema:
        type: integer
        format: int64

    endTimestamp:
      name: end_timestamp
      in: query
      description: Maximum timestamp filter in seconds (exclusive)
      required: false
      schema:
        type: integer
        format: int64

    startOffset:
      name: start_offset
      in: query
      description: Number of documents to skip
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0

    maxHits:
      name: max_hits
      in: query
      description: Maximum number of hits to return
      required: false
      schema:
        type: integer
        minimum: 0
        default: 20

    searchField:
      name: search_field
      in: query
      description: Comma-separated list of fields to search in
      required: false
      schema:
        type: string

    snippetFields:
      name: snippet_fields
      in: query
      description: Comma-separated list of fields to extract snippets from
      required: false
      schema:
        type: string

    sortBy:
      name: sort_by
      in: query
      description: Sort field(s). Prefix with - for descending order.
      required: false
      schema:
        type: string

    format:
      name: format
      in: query
      description: Output format
      required: false
      schema:
        type: string
        enum: [json, pretty_json]
        default: pretty_json

  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'

  schemas:
    ApiError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message
      example:
        message: "Index 'my-index' not found"

    ClusterState:
      type: object
      properties:
        cluster_id:
          type: string
          description: Unique identifier for the cluster
        node_id:
          type: string
          description: ID of the node serving the request
        num_live_nodes:
          type: integer
          description: Number of live nodes in the cluster
        live_nodes:
          type: array
          items:
            type: object
            properties:
              node_id:
                type: string
              listen_addr:
                type: string
              indexer_cpu_capacity:
                type: number

    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'

    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

    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

    SearchSettings:
      type: object
      properties:
        default_search_fields:
          type: array
          items:
            type: string
          description: Fields searched when no field is specified in the query

    RetentionPolicy:
      type: object
      properties:
        period:
          type: string
          description: Retention period (e.g. "90 days")
        schedule:
          type: string
          description: Cron schedule for retention enforcement

    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

    SplitList:
      type: object
      properties:
        offset:
          type: integer
        size:
          type: integer
        splits:
          type: array
          items:
            $ref: '#/components/schemas/SplitMetadata'

    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

    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Full-text search query
          example: "error AND service:api"
        start_timestamp:
          type: integer
          format: int64
          description: Minimum timestamp in seconds (inclusive)
        end_timestamp:
          type: integer
          format: int64
          description: Maximum timestamp in seconds (exclusive)
        start_offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of documents to skip
        max_hits:
          type: integer
          minimum: 0
          default: 20
          description: Maximum number of hits to return
        search_field:
          type: array
          items:
            type: string
          description: Fields to search in
        snippet_fields:
          type: array
          items:
            type: string
          description: Fields to extract snippets from
        sort_by:
          type: array
          items:
            type: string
          description: Fields to sort by (prefix with - for descending)
        aggs:
          type: object
          description: Elasticsearch-compatible aggregation definitions
          additionalProperties: true
        format:
          type: string
          enum: [json, pretty_json]
          default: pretty_json

    SearchResponse:
      type: object
      properties:
        hits:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Array of matching documents
        num_hits:
          type: integer
          format: int64
          description: Total number of matching documents
        elapsed_time_micros:
          type: integer
          format: int64
          description: Query execution time in microseconds
        errors:
          type: array
          items:
            type: string
          description: Non-fatal errors encountered during search
        aggregations:
          type: object
          additionalProperties: true
          description: Aggregation results

    IngestResponse:
      type: object
      properties:
        num_docs_for_processing:
          type: integer
          description: Number of documents submitted for processing
        num_ingested_docs:
          type: integer
          description: Number of documents successfully ingested
        num_rejected_docs:
          type: integer
          description: Number of documents rejected due to parse errors
        parse_failures:
          type: array
          items:
            type: object
            properties:
              reason:
                type: string
              document:
                type: string
          description: Details of parse failures (only if detailed_response=true)

    DeleteQuery:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Query matching documents to delete
          example: "level:debug"
        search_field:
          type: array
          items:
            type: string
          description: Fields to search in
        start_timestamp:
          type: integer
          format: int64
          description: Minimum timestamp in seconds
        end_timestamp:
          type: integer
          format: int64
          description: Maximum timestamp in seconds

    DeleteTask:
      type: object
      properties:
        create_timestamp:
          type: integer
          format: int64
          description: Unix timestamp when the task was created
        opstamp:
          type: integer
          format: int64
          description: Operation stamp for ordering
        delete_query:
          $ref: '#/components/schemas/DeleteQuery'

    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

    IndexTemplate:
      type: object
      required:
        - version
        - template_id
        - index_id_patterns
      properties:
        version:
          type: string
          description: Template format version
        template_id:
          type: string
          description: Unique template identifier
        index_id_patterns:
          type: array
          items:
            type: string
          description: Glob patterns matching index IDs this template applies to
        priority:
          type: integer
          description: Priority when multiple templates match (higher wins)
          default: 0
        description:
          type: string
          description: Human-readable template description
        doc_mapping:
          $ref: '#/components/schemas/DocMapping'
        indexing_settings:
          $ref: '#/components/schemas/IndexingSettings'
        search_settings:
          $ref: '#/components/schemas/SearchSettings'
        retention:
          $ref: '#/components/schemas/RetentionPolicy'