openapi: 3.0.3
info:
  title: LynxDB API
  version: 1.0.0
  description: |
    HTTP API of LynxDB, a columnar log store queried with OpenSearch Piped Processing Language (PPL).

    Queries start with a source (`source=main ...`) or a source command (`describe main`),
    followed by `| command` stages: `source=main status>=500 | stats count() as errors by host | sort - errors`.

    ## Envelopes

    Successful JSON responses wrap the payload in `data`, with a `meta` object (`took_ms`, `query_id`, `rows`, `stats`)
    when there is something to report. Errors use `{"error": {"code", "message", "suggestion"}}`; query compile
    errors add `position` (`line`, `column`) and `expected`.

    Compatibility endpoints (Elasticsearch, Splunk HEC, OTLP) answer in the format of their protocol.

    ## Authentication

    Off by default. When on, every `/api/...` route needs `Authorization: Bearer <token>`,
    `ApiKey <base64(id:token)>` or `Basic <base64(user:token)>`. Clients that cannot set headers may pass `_token`
    as a query parameter. `/health`, `/metrics` and routes outside `/api/` are not checked by the API key middleware.

    ## Bodies

    `Content-Encoding: gzip`, `zstd` or `snappy` bodies are decoded on every route. `POST /api/v1/ingest`
    and `/api/v1/ingest/raw` are bounded by `ingest.max_body_size` alone, as sent and decoded; every other
    route by `ingest.limits.max_compressed_body_bytes` as sent and `ingest.limits.max_decompressed_body_bytes`
    decoded, and by `ingest.max_body_size` as sent. A body over its limit answers `413` with
    `{"error": {"type": "request_body_too_large", "reason"}, "status": 413}`, the reason naming the setting;
    an unknown encoding answers `400` with `type` `invalid_request`.
  contact:
    name: LynxDB
    url: https://lynxdb.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: http://localhost:3100
    description: Local server

tags:
  - name: Query
    description: Run PPL queries, inspect plans, list the PPL catalog, manage jobs
  - name: Schema
    description: Fields, field values, indexes and the event histogram
  - name: Ingest
    description: Native ingest endpoints
  - name: Server
    description: Health, metrics, status, configuration and profiling
  - name: Auth
    description: API key management (only when authentication is on)
  - name: Elasticsearch
    description: Elasticsearch bulk ingest and setup probe stubs
  - name: Splunk HEC
    description: Splunk HTTP Event Collector ingest
  - name: OTLP
    description: OpenTelemetry log ingest

security:
  - BearerAuth: []
  - ApiKeyAuth: []
  - BasicAuth: []
  - {}

paths:

  # QUERY

  /api/v1/query:
    post:
      operationId: queryPost
      tags: [Query]
      summary: Run a PPL query
      description: |
        Runs a PPL query as a job and returns the result, or a job handle. Needs `query` scope.

        | `wait` | Mode | Response |
        |---|---|---|
        | absent or `null` | sync | `200` with the result; `202` with a job handle if the query outlives `query.sync_timeout` (30s) |
        | `0` | async | `202` with a job handle at once |
        | `N` > 0 | hybrid | `200` if the query finishes within N seconds, otherwise `202` with a job handle |

        Event queries return `data.type: events` with an `events` array. Queries whose result comes from
        an aggregation (`stats`, `timechart`, `chart`, `top`, `rare`, `describe`, `transpose`) return
        `data.type: aggregate` with `columns` and `rows`. The columns the query fixes come first, in its order;
        then the built-in fields, then the others alphabetically.

        Compile errors answer `400` (`SYNTAX_ERROR`, `SEMANTIC_ERROR`, `TYPE_ERROR`, `PLANNING_ERROR`) or
        `422` (`UNSUPPORTED_COMMAND`, `UNSUPPORTED_FUNCTION`, `UNSUPPORTED_FEATURE`). Failures while running answer
        `500 EXECUTION_ERROR`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            examples:
              events:
                summary: Events
                value:
                  q: 'source=main level=ERROR status>=500 | fields host, status, path | head 3'
              aggregate:
                summary: Aggregation over the last hour
                value:
                  q: 'source=main status>=500 | stats count() as errors, avg(response_time) as avg_ms by host | sort - errors | head 10'
                  from: '-1h'
              hybrid:
                summary: Wait up to 5 seconds, then return a job handle
                value:
                  q: 'source=main | stats count() by span(_time, 1h), level'
                  from: '-30d'
                  wait: 5
              async:
                summary: Return a job handle at once
                value:
                  q: 'source=main | stats dc(user) as users by host'
                  wait: 0
              paged:
                summary: Rows 3 to 5
                value:
                  q: 'source=main | stats count() as n by path | sort - n'
                  limit: 3
                  offset: 2
      responses:
        '200':
          description: The query finished
          headers:
            X-Query-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                events:
                  summary: Event result
                  value:
                    data:
                      type: events
                      events:
                        - {host: api-02, status: 500, path: /api/v1/orders}
                        - {host: web-01, status: 503, path: /api/v1/users}
                        - {host: api-01, status: 503, path: /api/v1/search}
                      total: 3
                      has_more: false
                    meta:
                      took_ms: 0.19
                      query_id: qry_f8b21fe1891075c3
                      rows: 3
                aggregate:
                  summary: Aggregate result
                  value:
                    data:
                      type: aggregate
                      columns: [errors, avg_ms, host]
                      rows:
                        - [48, 439, api-02]
                        - [43, 355.4, web-02]
                        - [41, 439.3, web-03]
                      total_rows: 3
                      has_more: false
                    meta:
                      took_ms: 0.218
                      query_id: qry_ff9a60bb26c70c81
                      rows: 3
        '202':
          description: The query runs as a job; poll `/api/v1/query/jobs/{id}` or follow its SSE stream
          headers:
            X-Query-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobHandleResponse'
        '400':
          $ref: '#/components/responses/QueryError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnsupportedQuery'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ExecutionError'
    get:
      operationId: queryGet
      tags: [Query]
      summary: Run a PPL query from query-string parameters
      description: Sync mode only. Returns the same envelope as `POST /api/v1/query`. Needs `query` scope.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          example: 'source=main status>=500 | stats count() as errors by host'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
            maximum: 50000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: format
          in: query
          schema:
            type: string
            enum: [json]
      responses:
        '200':
          description: The query finished
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '202':
          description: The query outlived `query.sync_timeout` and runs as a job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobHandleResponse'
        '400':
          $ref: '#/components/responses/QueryError'
        '422':
          $ref: '#/components/responses/UnsupportedQuery'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ExecutionError'

  /api/v1/query/stream:
    post:
      operationId: queryStream
      tags: [Query]
      summary: Run a PPL query and stream rows as NDJSON
      description: |
        Runs the query to the end, then writes one JSON object per row and a last line
        `{"__meta": {"total", "took_ms"}}`. A query that fails, at compile time or while running,
        answers with the normal error envelope and status. Needs `query` scope.

        Accepts `q`/`query`, `from`/`earliest` and `to`/`latest`.
        `limit`, `offset`, `wait`, and `format` are rejected with `400 VALIDATION_ERROR`.
        No row cap applies; use `head` in the query.
        Closing the connection while the query runs cancels it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryStreamRequest'
            example:
              q: 'source=main | stats count() as n by level'
      responses:
        '200':
          description: NDJSON rows
          content:
            application/x-ndjson:
              schema:
                type: string
              example: |
                {"n":294,"level":"ERROR"}
                {"n":359,"level":"INFO"}
                {"n":347,"level":"WARN"}
                {"__meta":{"total":3,"took_ms":0}}
        '400':
          $ref: '#/components/responses/QueryError'
        '422':
          $ref: '#/components/responses/UnsupportedQuery'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ExecutionError'

  /api/v1/query/explain:
    get:
      operationId: queryExplain
      tags: [Query]
      summary: Compile a query and return its plans
      description: |
        Returns the logical and optimized plans and scan hints without running the query.
        An invalid query answers `200` with `is_valid: false` and its compile errors.
        With `analyze=true`, also runs the query and adds `execution` (`took_ms`, `rows`).
        Any valid key can call it.
      parameters:
        - name: q
          in: query
          description: The PPL query; `query` is an alias
          required: true
          schema:
            type: string
          example: 'source=main status>=500 | stats count() as errors by host | sort - errors | head 5'
        - name: query
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - name: analyze
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: The plans, or the compile errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplainResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

  /api/v1/catalog:
    get:
      operationId: catalog
      tags: [Query]
      summary: PPL commands and functions with their support level
      description: |
        Fixed for a given binary. Carries `ETag` and `Cache-Control: public, max-age=86400`;
        a matching `If-None-Match` answers `304`. Any valid key can call it.
      parameters:
        - name: If-None-Match
          in: header
          schema:
            type: string
      responses:
        '200':
          description: The catalog
          headers:
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '304':
          description: The catalog has not changed

  /api/v1/query/jobs:
    get:
      operationId: listJobs
      tags: [Query]
      summary: List jobs
      description: |
        Running jobs and finished jobs younger than `query.job_ttl` (5m), the latest first. Needs `query` scope.
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [running, done, error, canceled]
      responses:
        '200':
          description: Jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

  /api/v1/query/jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/JobID'
    get:
      operationId: getJob
      tags: [Query]
      summary: State and result of a job
      description: |
        A running job carries `progress`; a done job carries `results`, limited to `query.default_result_limit` rows;
        a failed or canceled job carries `error`. Needs `query` scope.
      responses:
        '200':
          description: The job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelJob
      tags: [Query]
      summary: Cancel a job
      description: |
        Cancels the job and waits up to a second for it to stop. `canceled` is `true` when the job was running.
        Needs `admin` scope.
      responses:
        '200':
          description: The job after the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelJobResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/query/jobs/{id}/stream:
    parameters:
      - $ref: '#/components/parameters/JobID'
    get:
      operationId: streamJob
      tags: [Query]
      summary: Follow a job over Server-Sent Events
      description: |
        | Event | Data |
        |---|---|
        | `progress` | `{"status", "elapsed_ms"}`, once a second while the job runs |
        | `complete` | `{"data": <result>, "meta": {"took_ms", "query_id", "rows"}}` |
        | `failed` | `{"code", "message"}` |
        | `canceled` | `{"status", "elapsed_ms"}` |

        Needs `query` scope; `_token` carries the key for `EventSource` clients.
      security:
        - BearerAuth: []
        - TokenQuery: []
        - {}
      responses:
        '200':
          description: Event stream
          content:
            text/event-stream:
              schema:
                type: string
              example: |
                event: progress
                data: {"elapsed_ms":52,"status":"running"}

                event: complete
                data: {"data":{"type":"aggregate","columns":["n"],"rows":[[1010025]],"total_rows":1,"has_more":false},"meta":{"took_ms":4049.035,"query_id":"qry_cfb13bcc9a82770c","rows":1}}
        '404':
          $ref: '#/components/responses/NotFound'

  # SCHEMA

  /api/v1/histogram:
    get:
      operationId: histogram
      tags: [Schema]
      summary: Event counts per time bucket
      description: |
        The interval is the range divided by `buckets`, snapped to the nearest of 1s, 5s, 30s, 1m, 5m, 15m,
        1h, 6h and 1d (whole days above a day). Buckets start at multiples of the interval since the Unix epoch,
        from the one holding `from` to the last one that starts before `to`. Any valid key can call it.
      parameters:
        - name: from
          in: query
          schema:
            type: string
            default: '-1h'
        - name: to
          in: query
          schema:
            type: string
            default: now
        - name: buckets
          in: query
          schema:
            type: integer
            default: 60
            maximum: 1000
        - name: index
          in: query
          description: Count only this index; all indexes when absent
          schema:
            type: string
      responses:
        '200':
          description: Buckets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistogramResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

  /api/v1/fields:
    get:
      operationId: listFields
      tags: [Schema]
      summary: Field catalog
      description: The fields the indexes hold, each with the indexes that hold it. Any valid key can call it.
      parameters:
        - name: index
          in: query
          description: Only this index; `source` is an alias
          schema:
            type: string
        - name: source
          in: query
          schema:
            type: string
        - name: prefix
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldsResponse'

  /api/v1/fields/{name}/values:
    get:
      operationId: fieldValues
      tags: [Schema]
      summary: Most frequent values of a field
      description: Any valid key can call it.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
        - name: index
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/From'
        - name: since
          in: query
          description: Span back from now, such as `1h`; `from` wins when both are set
          schema:
            type: string
        - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Values with their counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldValuesResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

  /api/v1/indexes:
    get:
      operationId: listIndexes
      tags: [Schema]
      summary: List indexes
      description: Any valid key can call it.
      responses:
        '200':
          description: Indexes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexesResponse'

  /api/v1/indexes/{index}:
    parameters:
      - name: index
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getIndex
      tags: [Schema]
      summary: Describe an index with its settings
      description: Any valid key can call it.
      responses:
        '200':
          description: The index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: createIndex
      tags: [Schema]
      summary: Create an index with its own settings
      description: |
        Creates the index with the sort key, time fields and partition span of the body; a setting left out
        takes the server's `storage.*` setting. The settings are written to the index's directory before the
        index takes events and stay with the index across restarts and changes to the configuration.
        Repeating the call answers `200` with the index when it has every setting the body gives, and `409`
        when it has another; the settings of an index do not change. Needs `ingest` or `admin` scope.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexSettingsRequest'
            example:
              sort_key: [kind, commit.operation, commit.collection, did]
              time_fields: [time_us]
              partition: 1d
      responses:
        '201':
          description: The index was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexResponse'
        '200':
          description: The index exists with every setting the body gives
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ShuttingDown'

  /api/v1/indexes/{index}/compact:
    post:
      operationId: compactIndex
      tags: [Schema]
      summary: Merge an index into one sorted run per partition
      description: |
        Writes the events ingested so far, merges the parts of every partition of the index into one sorted run,
        and answers when that is done, which takes as long as the merge. Queries that run meanwhile read the parts
        as they were until the merge commits. Needs `ingest` or `admin` scope.
      parameters:
        - name: index
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: What the merge did
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ShuttingDown'

  # INGEST

  /api/v1/ingest:
    post:
      operationId: ingest
      tags: [Ingest]
      summary: Ingest NDJSON events
      description: |
        Appends the lines of the body, unchanged, to one index: the `index` query parameter, else the
        `X-Index` header, else `main`. A line that is not a JSON object becomes an event holding the text in `_raw`.
        The event time comes from the first of `storage.time_fields` an event holds, else the time of arrival.
        Needs `ingest` scope.
      parameters:
        - name: index
          in: query
          schema:
            type: string
        - name: X-Index
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-ndjson:
            schema:
              type: string
            example: |
              {"_time":"2026-11-17T08:00:00Z","level":"info","msg":"user login","user_id":42}
              {"timestamp":"2026-11-17T08:00:05Z","level":"error","msg":"payment failed","order":{"id":7,"total":19.5}}
      responses:
        '200':
          description: Lines accepted and rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '503':
          $ref: '#/components/responses/ShuttingDown'

  /api/v1/ingest/raw:
    post:
      operationId: ingestRaw
      tags: [Ingest]
      summary: Ingest log text
      description: |
        One event per line. A line that is a JSON object passes unchanged. Any other line becomes an event with the
        line in `_raw`, its leading timestamp as `_time`, its `key=value` pairs as typed fields, and the labels of the
        headers as `source`, `sourcetype` and `host`. The index is `X-Index`, else the `index` query parameter,
        else `main`. When the body is cut off after some events were stored, the response carries
        `truncated: true` and a `warning`. Needs `ingest` scope.
      parameters:
        - name: X-Index
          in: header
          schema:
            type: string
            maxLength: 256
        - name: index
          in: query
          schema:
            type: string
        - name: X-Source
          in: header
          schema:
            type: string
            default: http
            maxLength: 256
        - name: X-Source-Type
          in: header
          schema:
            type: string
            default: raw
            maxLength: 256
        - name: X-Host
          in: header
          schema:
            type: string
            maxLength: 256
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
            example: |
              2026-11-17T08:00:00.000Z level=warn path=/api/users latency_ms=812 slow request
      responses:
        '200':
          description: Lines accepted and rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ShuttingDown'

  /api/v1/ingest/hec:
    post:
      operationId: ingestHEC
      tags: [Ingest, Splunk HEC]
      summary: Ingest Splunk HEC events with a LynxDB key
      description: |
        The Splunk HEC event handler, authenticated with a LynxDB key of `ingest` scope instead of a Splunk token.
        Events go to the `main` index.
      parameters:
        - $ref: '#/components/parameters/SplunkChannel'
      requestBody:
        $ref: '#/components/requestBodies/HECEvents'
      responses:
        '200':
          $ref: '#/components/responses/HECSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # SERVER

  /health:
    get:
      operationId: health
      tags: [Server]
      summary: Health check
      security: []
      responses:
        '200':
          description: The server is up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /metrics:
    get:
      operationId: metrics
      tags: [Server]
      summary: Prometheus metrics
      security: []
      responses:
        '200':
          description: Prometheus text exposition
          content:
            text/plain:
              schema:
                type: string

  /api/v1/status:
    get:
      operationId: status
      tags: [Server]
      summary: Server snapshot
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'

  /api/v1/stats:
    get:
      operationId: stats
      tags: [Server]
      summary: Indexes, storage totals and job counts
      responses:
        '200':
          description: Stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'

  /api/v1/config:
    get:
      operationId: getConfig
      tags: [Server]
      summary: Running configuration
      description: |
        Needs `admin` scope. Durations in `query` and `http` are integer nanoseconds; the others are text.
      responses:
        '200':
          description: Configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObject'
        '403':
          $ref: '#/components/responses/Forbidden'
    patch:
      operationId: patchConfig
      tags: [Server]
      summary: Change the running configuration
      description: |
        Merges the body into the running configuration, validates it and applies it like a `SIGHUP` reload.
        Accepted top-level keys: `retention`, `log_level`, `listen`, `query`, `ingest`, `storage`, `http`, `syslog`.
        Settings that take effect only after a restart are listed in `restart_required`. Needs a root key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              log_level: debug
              query: {default_result_limit: 500}
      responses:
        '200':
          description: The resulting configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPatchResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/debug/pprof/{profile}:
    get:
      operationId: pprof
      tags: [Server]
      summary: Go runtime profiles
      parameters:
        - name: profile
          in: path
          required: true
          schema:
            type: string
            enum: [profile, trace, heap, allocs, goroutine, mutex, block, threadcreate, cmdline, symbol]
        - name: seconds
          in: query
          description: Duration of `profile` and `trace`
          schema:
            type: integer
      responses:
        '200':
          description: The profile
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  # AUTH

  /api/v1/auth/keys:
    post:
      operationId: createKey
      tags: [Auth]
      summary: Create an API key
      description: Needs a root key. Answers `404` when authentication is off.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyRequest'
            example:
              name: filebeat
              scope: ingest
              expires_in: 90d
              description: edge shipper
      responses:
        '201':
          description: The key and its token, shown once
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedKeyResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: listKeys
      tags: [Auth]
      summary: List API keys
      description: Needs a root key. Answers `404` when authentication is off.
      responses:
        '200':
          description: Keys without their tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyListResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/auth/keys/{id}:
    delete:
      operationId: revokeKey
      tags: [Auth]
      summary: Revoke an API key
      description: Needs a root key. Answers `404` when authentication is off.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Revoked
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The key is the last root key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/rotate-root:
    post:
      operationId: rotateRoot
      tags: [Auth]
      summary: Replace the calling root key
      description: Needs a root key. Answers `404` when authentication is off.
      responses:
        '200':
          description: The replacement key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateRootResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ELASTICSEARCH

  /_bulk:
    post:
      operationId: esBulk
      tags: [Elasticsearch]
      summary: Elasticsearch bulk ingest
      description: |
        `index` and `create` actions append their document line unchanged to the action's `_index`, else `main`.
        `update` and `delete` actions fail per item. The documents are durable before the response.
        Outside `/api/`, so with authentication on it answers `401`; use `/api/v1/es/_bulk`.
      security: []
      requestBody:
        $ref: '#/components/requestBodies/ESBulk'
      responses:
        '200':
          $ref: '#/components/responses/ESBulkResult'
        '400':
          $ref: '#/components/responses/ESError'
        '413':
          $ref: '#/components/responses/ESError'
        '503':
          $ref: '#/components/responses/ESError'

  /{index}/_bulk:
    post:
      operationId: esIndexBulk
      tags: [Elasticsearch]
      summary: Elasticsearch bulk ingest into an index
      description: Same as `/_bulk`, with `{index}` for actions that name no `_index`.
      security: []
      parameters:
        - $ref: '#/components/parameters/ESIndex'
      requestBody:
        $ref: '#/components/requestBodies/ESBulk'
      responses:
        '200':
          $ref: '#/components/responses/ESBulkResult'
        '400':
          $ref: '#/components/responses/ESError'

  /_data_stream/{data_stream}/_bulk:
    post:
      operationId: esDataStreamBulk
      tags: [Elasticsearch]
      summary: Elasticsearch bulk ingest into a data stream
      description: Same as `/_bulk`, with the data stream name for actions that name no `_index`.
      security: []
      parameters:
        - $ref: '#/components/parameters/DataStream'
      requestBody:
        $ref: '#/components/requestBodies/ESBulk'
      responses:
        '200':
          $ref: '#/components/responses/ESBulkResult'
        '400':
          $ref: '#/components/responses/ESError'

  /api/v1/es/_bulk:
    post:
      operationId: esPrefixedBulk
      tags: [Elasticsearch]
      summary: Elasticsearch bulk ingest under /api/v1/es
      description: Same as `/_bulk`, authenticated with an `ingest` key.
      requestBody:
        $ref: '#/components/requestBodies/ESBulk'
      responses:
        '200':
          $ref: '#/components/responses/ESBulkResult'
        '400':
          $ref: '#/components/responses/ESError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/ESError'
        '503':
          $ref: '#/components/responses/ESError'

  /api/v1/es/_data_stream/{data_stream}/_bulk:
    post:
      operationId: esPrefixedDataStreamBulk
      tags: [Elasticsearch]
      summary: Elasticsearch data stream bulk ingest under /api/v1/es
      parameters:
        - $ref: '#/components/parameters/DataStream'
      requestBody:
        $ref: '#/components/requestBodies/ESBulk'
      responses:
        '200':
          $ref: '#/components/responses/ESBulkResult'
        '400':
          $ref: '#/components/responses/ESError'

  /api/v1/es/{index}/_doc:
    post:
      operationId: esIndexDoc
      tags: [Elasticsearch]
      summary: Elasticsearch single-document ingest
      description: Appends one JSON object to `{index}`. Needs `ingest` scope.
      parameters:
        - $ref: '#/components/parameters/ESIndex'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              message: single event
              '@timestamp': '2026-11-17T09:00:02Z'
              level: info
      responses:
        '201':
          description: Stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESIndexDocResponse'
        '400':
          $ref: '#/components/responses/ESError'
        '503':
          $ref: '#/components/responses/ESError'

  /:
    get:
      operationId: esHandshake
      tags: [Elasticsearch]
      summary: Elasticsearch cluster handshake
      security: []
      responses:
        '200':
          description: Cluster description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESClusterInfo'

  /api/v1/es:
    get:
      operationId: esPrefixedHandshake
      tags: [Elasticsearch]
      summary: Elasticsearch cluster handshake under /api/v1/es (also with a trailing slash)
      responses:
        '200':
          description: Cluster description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESClusterInfo'

  /{index}:
    head:
      operationId: esIndexHead
      tags: [Elasticsearch]
      summary: Index existence probe
      description: Answers `200` for any index name; `HEAD /api/v1/es/{index}` answers the same.
      security: []
      parameters:
        - $ref: '#/components/parameters/ESIndex'
      responses:
        '200':
          description: Present

  /api/v1/es/{index}:
    put:
      operationId: esCreateIndex
      tags: [Elasticsearch]
      summary: Index creation (not supported)
      parameters:
        - $ref: '#/components/parameters/ESIndex'
      responses:
        '501':
          $ref: '#/components/responses/ESUnsupported'

  /_xpack:
    get:
      operationId: esXPack
      tags: [Elasticsearch]
      summary: X-Pack feature summary stub (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_xpack/license:
    get:
      operationId: esXPackLicense
      tags: [Elasticsearch]
      summary: License stub (also /_license, and both under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_cat/templates:
    get:
      operationId: esCatTemplates
      tags: [Elasticsearch]
      summary: Empty template list (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESEmptyArray'

  /_cat/indices:
    get:
      operationId: esCatIndices
      tags: [Elasticsearch]
      summary: Empty index list (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESEmptyArray'

  /_cluster/health:
    get:
      operationId: esClusterHealth
      tags: [Elasticsearch]
      summary: Green single-node health (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_index_template/{name}:
    parameters:
      - $ref: '#/components/parameters/StubName'
    get:
      operationId: esGetIndexTemplate
      tags: [Elasticsearch]
      summary: Empty index template list (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'
    put:
      operationId: esPutIndexTemplate
      tags: [Elasticsearch]
      summary: Acknowledges and stores nothing (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESAcknowledged'

  /_ilm/policy/{name}:
    get:
      operationId: esGetILMPolicy
      tags: [Elasticsearch]
      summary: No ILM policies (also under /api/v1/es); PUT under /api/v1/es answers 501
      security: []
      parameters:
        - $ref: '#/components/parameters/StubName'
      responses:
        '404':
          $ref: '#/components/responses/ESStub'

  /_ingest/pipeline/{name}:
    get:
      operationId: esGetIngestPipeline
      tags: [Elasticsearch]
      summary: No ingest pipelines (also under /api/v1/es); PUT under /api/v1/es answers 501
      security: []
      parameters:
        - $ref: '#/components/parameters/StubName'
      responses:
        '404':
          $ref: '#/components/responses/ESStub'

  /_nodes/{path}:
    get:
      operationId: esNodes
      tags: [Elasticsearch]
      summary: Minimal node HTTP info (also under /api/v1/es)
      security: []
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_alias:
    get:
      operationId: esAlias
      tags: [Elasticsearch]
      summary: Empty aliases (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_data_stream/{name}:
    parameters:
      - $ref: '#/components/parameters/StubName'
    get:
      operationId: esGetDataStream
      tags: [Elasticsearch]
      summary: Empty data stream list (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'
    put:
      operationId: esPutDataStream
      tags: [Elasticsearch]
      summary: Acknowledges and stores nothing (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESAcknowledged'

  /_search:
    get:
      operationId: esSearch
      tags: [Elasticsearch]
      summary: Empty hits (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  /_security/user/_authenticate:
    post:
      operationId: esAuthenticate
      tags: [Elasticsearch]
      summary: Authenticated user stub (also under /api/v1/es)
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ESStub'

  # SPLUNK HEC

  /services/collector:
    post:
      operationId: hecCollector
      tags: [Splunk HEC]
      summary: Splunk HEC event ingest
      description: |
        One HEC event object per line; lines that are not valid JSON are skipped and counted in `skipped_lines`.
        Events go to the `main` index. Needs `Authorization: Splunk <token>` with a non-empty token.
        `/services/collector/event` is the same route.
      security:
        - SplunkToken: []
      parameters:
        - $ref: '#/components/parameters/SplunkChannel'
      requestBody:
        $ref: '#/components/requestBodies/HECEvents'
      responses:
        '200':
          $ref: '#/components/responses/HECSuccess'
        '401':
          $ref: '#/components/responses/HECUnauthorized'
        '404':
          $ref: '#/components/responses/HECDisabled'

  /services/collector/event:
    post:
      operationId: hecEvent
      tags: [Splunk HEC]
      summary: Splunk HEC event ingest
      security:
        - SplunkToken: []
      parameters:
        - $ref: '#/components/parameters/SplunkChannel'
      requestBody:
        $ref: '#/components/requestBodies/HECEvents'
      responses:
        '200':
          $ref: '#/components/responses/HECSuccess'
        '401':
          $ref: '#/components/responses/HECUnauthorized'
        '404':
          $ref: '#/components/responses/HECDisabled'

  /services/collector/raw:
    post:
      operationId: hecRaw
      tags: [Splunk HEC]
      summary: Splunk HEC raw ingest
      description: One event per line. Events go to the `main` index; `index` stands in for an empty `source`.
      security:
        - SplunkToken: []
      parameters:
        - name: source
          in: query
          schema:
            type: string
        - name: sourcetype
          in: query
          schema:
            type: string
        - name: host
          in: query
          schema:
            type: string
        - name: index
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/SplunkChannel'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          $ref: '#/components/responses/HECSuccess'
        '401':
          $ref: '#/components/responses/HECUnauthorized'
        '404':
          $ref: '#/components/responses/HECDisabled'

  /services/collector/ack:
    post:
      operationId: hecAck
      tags: [Splunk HEC]
      summary: Splunk HEC acknowledgements
      security:
        - SplunkToken: []
      parameters:
        - $ref: '#/components/parameters/SplunkChannel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                acks:
                  type: array
                  items:
                    type: integer
            example:
              acks: [1, 2]
      responses:
        '200':
          description: The state of each acknowledgement ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  acks:
                    type: object
                    additionalProperties:
                      type: boolean
              example:
                acks: {'1': true, '2': false}
        '400':
          description: '`{"text": "Invalid ack request", "code": 5}`'
        '401':
          $ref: '#/components/responses/HECUnauthorized'
        '404':
          $ref: '#/components/responses/HECDisabled'

  /services/collector/health:
    get:
      operationId: hecHealth
      tags: [Splunk HEC]
      summary: Splunk HEC health
      security: []
      responses:
        '200':
          description: '`{"text": "HEC is healthy", "code": 17}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HECResponse'
        '404':
          $ref: '#/components/responses/HECDisabled'

  # OTLP

  /api/v1/otlp/v1/logs:
    post:
      operationId: otlpLogsJSON
      tags: [OTLP]
      summary: OTLP/HTTP JSON logs on the API port
      description: |
        Takes OTLP JSON only. `resource.attributes["deployment.environment"]` names the target index, else `main`.
        Any valid key can call it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: '`{}`'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The body is not valid OTLP JSON (`INVALID_JSON`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: '`application/x-protobuf` is not accepted on this route (`INVALID_REQUEST`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/logs:
    servers:
      - url: http://localhost:4318
        description: OTLP/HTTP listener (`ingest.otlp.http_listen`)
    post:
      operationId: otlpLogs
      tags: [OTLP]
      summary: OTLP/HTTP logs
      description: Protobuf or JSON. Records go to the `main` index; records with an empty body are dropped.
      security: []
      requestBody:
        required: true
        content:
          application/x-protobuf:
            schema:
              type: string
              format: binary
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: An empty `ExportLogsServiceResponse`
        '400':
          description: The body does not decode
        '415':
          description: Unsupported content type
        '503':
          description: The events could not be stored

  /v1/traces:
    servers:
      - url: http://localhost:4318
    post:
      operationId: otlpTraces
      tags: [OTLP]
      summary: Accepted and discarded
      security: []
      responses:
        '200':
          description: An empty `ExportTraceServiceResponse`

  /v1/metrics:
    servers:
      - url: http://localhost:4318
    post:
      operationId: otlpMetrics
      tags: [OTLP]
      summary: Accepted and discarded
      security: []
      responses:
        '200':
          description: An empty `ExportMetricsServiceResponse`

components:

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    BasicAuth:
      type: http
      scheme: basic
      description: The password is the token; the user name is ignored.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: '`ApiKey <base64(id:token)>`, as sent by Elasticsearch clients.'
    TokenQuery:
      type: apiKey
      in: query
      name: _token
      description: For clients that cannot set headers, such as `EventSource`.
    SplunkToken:
      type: apiKey
      in: header
      name: Authorization
      description: '`Splunk <token>`'

  parameters:
    From:
      name: from
      in: query
      description: 'Start time, inclusive: relative (`-1h`, `-7d`, `-1d@d`), `now`, or absolute (`2026-11-17T08:00:00Z`, `2026-11-17`)'
      schema:
        type: string
      example: '-1h'
    To:
      name: to
      in: query
      description: End time, exclusive; same formats as `from`
      schema:
        type: string
    JobID:
      name: id
      in: path
      required: true
      schema:
        type: string
      example: qry_2d2d123959b57199
    ESIndex:
      name: index
      in: path
      required: true
      schema:
        type: string
    DataStream:
      name: data_stream
      in: path
      required: true
      schema:
        type: string
    StubName:
      name: name
      in: path
      required: true
      schema:
        type: string
    SplunkChannel:
      name: X-Splunk-Request-Channel
      in: header
      description: When set, the events are durable before the response and an `ackId` is returned
      schema:
        type: string

  requestBodies:
    ESBulk:
      required: true
      content:
        application/x-ndjson:
          schema:
            type: string
          example: |
            {"index":{"_index":"logs"}}
            {"message":"hello from filebeat","@timestamp":"2026-11-17T09:00:00Z","level":"info"}
            {"create":{"_index":"logs"}}
            {"message":"cpu usage high","@timestamp":"2026-11-17T09:00:01Z","host":"web-01"}
    HECEvents:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HECEvent'
          example:
            event: user login succeeded
            time: 1763370000
            host: web-01
            source: auth-service
            sourcetype: json
            fields: {level: info}

  responses:
    QueryError:
      description: The request is invalid or the query does not compile
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            syntax:
              summary: SYNTAX_ERROR
              value:
                error:
                  code: SYNTAX_ERROR
                  message: 'syntax error at line 1, column 29: expected an expression'
                  position: {line: 1, column: 29}
                  expected: [expression]
            semantic:
              summary: SEMANTIC_ERROR
              value:
                error:
                  code: SEMANTIC_ERROR
                  message: 'semantic error at line 1, column 50: field status not found (available fields: n, host)'
                  position: {line: 1, column: 50}
                  suggestion: 'available fields: n, host'
            format:
              summary: Unsupported format
              value:
                error:
                  code: VALIDATION_ERROR
                  message: 'unsupported format "csv"; only "json" is supported'
                  suggestion: Use the default JSON response, or POST /api/v1/query/stream for NDJSON exports.
    UnsupportedQuery:
      description: The query uses PPL that LynxDB does not run
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNSUPPORTED_FEATURE
              message: 'unsupported_feature error at line 1, column 31: patterns method=brain is not supported; use method=simple_pattern'
              position: {line: 1, column: 31}
    ExecutionError:
      description: The query failed while running (`EXECUTION_ERROR`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: '`query.max_concurrent` queries run, or the per-IP rate limit was hit (`TOO_MANY_REQUESTS`)'
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: A parameter is missing or invalid (`VALIDATION_ERROR`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: No credentials (`AUTH_REQUIRED`) or credentials that match no key (`INVALID_TOKEN`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The key lacks the scope or root right the endpoint needs (`FORBIDDEN`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: No such job, key or index, or authentication is off on an `/auth` route (`NOT_FOUND`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The index exists with other settings than the request gives (`CONFLICT`); the message names the first that differs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: The body is over its size limit (`request_body_too_large`, the reason naming the setting), or a body sent without `Content-Length` grows past `ingest.max_body_size` (`INVALID_REQUEST`)
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/ESErrorResponse'
    ShuttingDown:
      description: The server is stopping (`SHUTTING_DOWN`)
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ESBulkResult:
      description: Per-item results; `errors` is true when any item failed
      headers:
        X-Elastic-Product:
          schema:
            type: string
            enum: [Elasticsearch]
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ESBulkResponse'
          example:
            took: 11
            errors: false
            items:
              - index: {_id: 6d9b0922f5d2a1dc62c2e0cb, _index: logs, status: 201, result: created}
              - create: {_id: a69dde78334e9ebc64b0a249, _index: logs, status: 201, result: created}
    ESError:
      description: An Elasticsearch-style error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ESErrorResponse'
    ESStub:
      description: A fixed Elasticsearch-shaped response
      content:
        application/json:
          schema:
            type: object
    ESEmptyArray:
      description: An empty array
      content:
        application/json:
          schema:
            type: array
            items: {}
    ESAcknowledged:
      description: '`{"acknowledged": true}`'
      content:
        application/json:
          schema:
            type: object
            properties:
              acknowledged:
                type: boolean
    ESUnsupported:
      description: '`{"error": "unsupported Elasticsearch management endpoint", "status": 501}`'
      content:
        application/json:
          schema:
            type: object
    HECSuccess:
      description: The events are stored
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HECResponse'
          example:
            code: 0
            text: Success
    HECUnauthorized:
      description: '`{"text": "Token is required", "code": 2}` or `{"text": "Invalid token", "code": 3}`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HECResponse'
    HECDisabled:
      description: '`ingest.splunk_hec.enabled` is false: `{"text": "HEC is disabled", "code": 4}`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HECResponse'

  schemas:
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum:
                - SYNTAX_ERROR
                - SEMANTIC_ERROR
                - TYPE_ERROR
                - PLANNING_ERROR
                - UNSUPPORTED_COMMAND
                - UNSUPPORTED_FUNCTION
                - UNSUPPORTED_FEATURE
                - EXECUTION_ERROR
                - QUERY_TOO_LARGE
                - TOO_MANY_REQUESTS
                - VALIDATION_ERROR
                - INVALID_JSON
                - INVALID_REQUEST
                - AUTH_REQUIRED
                - INVALID_TOKEN
                - FORBIDDEN
                - NOT_FOUND
                - CONFLICT
                - LAST_ROOT_KEY
                - SHUTTING_DOWN
                - INTERNAL_ERROR
            message:
              type: string
            suggestion:
              type: string
            position:
              $ref: '#/components/schemas/Position'
            expected:
              type: array
              items:
                type: string
    ESErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            reason:
              type: string
        status:
          type: integer
    Position:
      type: object
      properties:
        line:
          type: integer
        column:
          type: integer
    DataObject:
      type: object
      properties:
        data:
          type: object
    Meta:
      type: object
      properties:
        took_ms:
          type: number
        query_id:
          type: string
        rows:
          type: integer
          description: Rows the query produced, before `offset` and `limit`
        stats:
          type: object
          description: >-
            What the query read, present when the columnar executor ran the whole plan. Blocks are
            counted once each: opened (`blocks`), ruled out before that (`skipped_by_key`,
            `skipped_by_token`, `skipped_by_time`, `skipped_as_empty`), rejected from statistics
            (`skipped_by_stats`), or answered from the part index (`counted_by_index`,
            `counted_by_entries`, `counted_by_time`). The blocks of a count by buckets of time
            that were counted row by row are counted by why: the filter passed only some of their
            rows (`time_missed_filter`), they kept no rows by time in buckets that divide those of
            the query (`time_missed_record`), a column key held several values in the block
            (`time_missed_keys`), or a value in some of its rows only (`time_missed_nulls`).
          properties:
            blocks: {type: integer}
            skipped_by_key: {type: integer}
            skipped_by_token: {type: integer}
            skipped_by_time: {type: integer}
            skipped_as_empty: {type: integer}
            skipped_by_stats: {type: integer}
            counted_by_index: {type: integer}
            counted_by_entries: {type: integer}
            counted_by_time: {type: integer}
            time_missed_filter: {type: integer}
            time_missed_record: {type: integer}
            time_missed_keys: {type: integer}
            time_missed_nulls: {type: integer}
            columns_searched: {type: integer}
            columns_skipped_by_token: {type: integer}
            blocks_matched: {type: integer}
            rows_matched: {type: integer}
            held_bytes: {type: integer}
            ordered:
              type: boolean
              description: The groups were aggregated in sort key order
            hashed_for:
              type: string
              description: What kept a plan laid out for sort key order from running in it
    QueryRequest:
      type: object
      properties:
        q:
          type: string
          description: The PPL query; required unless `query` is set
        query:
          type: string
          description: Alias for `q`
        from:
          type: string
        to:
          type: string
        earliest:
          type: string
          description: Alias for `from`
        latest:
          type: string
          description: Alias for `to`
        limit:
          type: integer
          description: Default `query.default_result_limit` (1000), capped at `query.max_result_limit` (50000)
        offset:
          type: integer
        wait:
          type: number
          nullable: true
          description: Absent or null for sync, 0 for async, N seconds for hybrid
        format:
          type: string
          enum: [json]
          description: '`json` or empty. Any other value is a `400 VALIDATION_ERROR`'
    QueryStreamRequest:
      type: object
      description: '`limit`, `offset`, `wait`, and `format` are rejected with `400 VALIDATION_ERROR`.'
      properties:
        q:
          type: string
        query:
          type: string
        from:
          type: string
        to:
          type: string
        earliest:
          type: string
        latest:
          type: string
    EventsResult:
      type: object
      properties:
        type:
          type: string
          enum: [events]
        events:
          type: array
          items:
            type: object
        total:
          type: integer
        has_more:
          type: boolean
    AggregateResult:
      type: object
      properties:
        type:
          type: string
          enum: [aggregate]
        columns:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items: {}
        total_rows:
          type: integer
        has_more:
          type: boolean
    QueryResponse:
      type: object
      properties:
        data:
          oneOf:
            - $ref: '#/components/schemas/EventsResult'
            - $ref: '#/components/schemas/AggregateResult'
        meta:
          $ref: '#/components/schemas/Meta'
    JobProgress:
      type: object
      properties:
        status:
          type: string
          enum: [running, done, error, canceled]
        elapsed_ms:
          type: integer
    JobHandleResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum: [job]
            job_id:
              type: string
            status:
              type: string
              enum: [running]
            progress:
              $ref: '#/components/schemas/JobProgress'
        meta:
          $ref: '#/components/schemas/Meta'
      example:
        data:
          type: job
          job_id: qry_2d2d123959b57199
          status: running
          progress: {status: running, elapsed_ms: 0}
        meta:
          query_id: qry_2d2d123959b57199
    JobResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum: [job]
            job_id:
              type: string
            status:
              type: string
              enum: [running, done, error, canceled]
            query:
              type: string
            created_at:
              type: string
              format: date-time
            completed_at:
              type: string
              format: date-time
              description: When the job is done
            progress:
              $ref: '#/components/schemas/JobProgress'
            results:
              oneOf:
                - $ref: '#/components/schemas/EventsResult'
                - $ref: '#/components/schemas/AggregateResult'
            error:
              type: object
              description: When the job failed or was canceled
              properties:
                code:
                  type: string
                message:
                  type: string
        meta:
          $ref: '#/components/schemas/Meta'
    JobListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            jobs:
              type: array
              items:
                type: object
                properties:
                  job_id:
                    type: string
                  query:
                    type: string
                  status:
                    type: string
                  created_at:
                    type: string
                    format: date-time
    CancelJobResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            job_id:
              type: string
            status:
              type: string
            canceled:
              type: boolean
            completed_at:
              type: string
              format: date-time
    ExplainResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            is_valid:
              type: boolean
            errors:
              type: array
              items:
                $ref: '#/components/schemas/CompileError'
            parsed:
              type: object
              properties:
                result_type:
                  type: string
                  enum: [events, aggregate]
                estimated_cost:
                  type: string
                  enum: [low, medium, high]
                uses_full_scan:
                  type: boolean
                fields_read:
                  type: array
                  nullable: true
                  items:
                    type: string
                search_terms:
                  type: array
                  nullable: true
                  items:
                    type: string
                has_time_bounds:
                  type: boolean
                logical_plan:
                  type: string
                optimized_plan:
                  type: string
                compile_ms:
                  type: number
                optimizer_rules:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                source_scope:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: [single, list, glob, all]
                    sources:
                      type: array
                      items:
                        type: string
                    pattern:
                      type: string
                    total_sources_available:
                      type: integer
            execution:
              type: object
              description: With `analyze=true`
              properties:
                took_ms:
                  type: number
                rows:
                  type: integer
    CompileError:
      type: object
      properties:
        kind:
          type: string
          enum: [syntax, semantic, type, unsupported_command, unsupported_function, unsupported_feature]
        message:
          type: string
        position:
          $ref: '#/components/schemas/Position'
        expected:
          type: array
          items:
            type: string
        suggestion:
          type: string
    CatalogResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            language:
              type: string
              enum: [ppl]
            commands:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  support:
                    type: string
                    enum: [full, partial, unsupported]
                  notes:
                    type: string
            functions:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  kind:
                    type: string
                    enum: [scalar, aggregate]
                  category:
                    type: string
                  support:
                    type: string
                    enum: [full, unsupported]
                  lowering:
                    type: string
                  notes:
                    type: string
                  doc:
                    type: string
                  unsupported:
                    type: string
    HistogramResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            interval:
              type: string
              example: 15m0s
            buckets:
              type: array
              items:
                type: object
                properties:
                  time:
                    type: string
                    format: date-time
                  count:
                    type: integer
            total:
              type: integer
        meta:
          $ref: '#/components/schemas/Meta'
    FieldsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            fields:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  indexes:
                    type: array
                    items:
                      type: string
      example:
        data:
          fields:
            - {name: status, indexes: [backend, main]}
    FieldValuesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            field:
              type: string
            values:
              type: array
              items:
                type: object
                properties:
                  value: {}
                  count:
                    type: integer
        meta:
          $ref: '#/components/schemas/Meta'
    Index:
      type: object
      properties:
        name:
          type: string
        events:
          type: integer
        bytes:
          type: integer
        parts:
          type: integer
        merges_running:
          type: integer
          description: Merges of the index's parts under way
        runs_to_merge:
          type: integer
          description: Sorted runs that background merging is still to merge; with merges_running at zero the index is quiet
        first_event:
          type: string
          format: date-time
        last_event:
          type: string
          format: date-time
        sort_key:
          type: array
          items:
            type: string
          description: Fields whose values order the rows of the index; empty orders them by time
        time_fields:
          type: array
          items:
            type: string
          description: Fields whose value becomes the time of an event, tried in their order
        partition:
          type: string
          description: Span of time whose events the index keeps apart, such as `1d` or `1h0m0s`
    IndexResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Index'
    IndexSettingsRequest:
      type: object
      additionalProperties: false
      properties:
        sort_key:
          type: array
          maxItems: 32
          items:
            type: string
          description: Field paths, such as `commit.collection`, that order the rows; `[]` orders them by time. Default `storage.sort_key`
        time_fields:
          type: array
          maxItems: 32
          items:
            type: string
          description: Field paths whose value becomes the time of an event, tried in their order. Default `storage.time_fields`
        partition:
          type: string
          description: A span from one minute to 366 days, such as `1h` or `1d`. Default `storage.partition`
    CompactResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            index:
              type: string
            parts_before:
              type: integer
            parts:
              type: integer
            bytes_before:
              type: integer
            bytes:
              type: integer
            seconds:
              type: number
              description: Time the request took, the write of pending events included
    IndexesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            indexes:
              type: array
              items:
                $ref: '#/components/schemas/Index'
    IngestResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            accepted:
              type: integer
            failed:
              type: integer
            truncated:
              type: boolean
              description: '`/ingest/raw` only: the body was cut off after some events were stored'
            warning:
              type: string
      example:
        data: {accepted: 3, failed: 0}
    HECEvent:
      type: object
      properties:
        event:
          description: Text, or an object stored as its JSON text
        time:
          type: number
          description: Unix seconds
        host:
          type: string
        source:
          type: string
        sourcetype:
          type: string
        index:
          type: string
          description: Stored as `source_tag`, or as `source` when `source` is empty
        fields:
          type: object
    HECResponse:
      type: object
      properties:
        text:
          type: string
        code:
          type: integer
        ackId:
          type: integer
        skipped_lines:
          type: integer
    ESBulkResponse:
      type: object
      properties:
        took:
          type: integer
        errors:
          type: boolean
        items:
          type: array
          items:
            type: object
            properties:
              index:
                $ref: '#/components/schemas/ESBulkItem'
              create:
                $ref: '#/components/schemas/ESBulkItem'
    ESBulkItem:
      type: object
      properties:
        _id:
          type: string
        _index:
          type: string
        status:
          type: integer
        result:
          type: string
        error:
          type: object
          properties:
            type:
              type: string
            reason:
              type: string
    ESIndexDocResponse:
      type: object
      properties:
        _id:
          type: string
        _index:
          type: string
        result:
          type: string
          enum: [created]
    ESClusterInfo:
      type: object
      properties:
        name:
          type: string
        cluster_name:
          type: string
        cluster_uuid:
          type: string
        version:
          type: object
          properties:
            number:
              type: string
              example: 8.15.0
        tagline:
          type: string
    HealthResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: string
              enum: [healthy]
            version:
              type: string
    StatusResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            version:
              type: string
            uptime_seconds:
              type: integer
            health:
              type: string
              enum: [healthy]
            storage:
              type: object
              properties:
                used_bytes:
                  type: integer
            events:
              type: object
              properties:
                total:
                  type: integer
            queries:
              type: object
              properties:
                active:
                  type: integer
            retention:
              type: object
              properties:
                policy:
                  type: string
                oldest_event:
                  type: string
                  format: date-time
    StatsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            uptime_seconds:
              type: integer
            storage_bytes:
              type: integer
            total_events:
              type: integer
            index_count:
              type: integer
            part_count:
              type: integer
            merges_running:
              type: integer
            runs_to_merge:
              type: integer
            oldest_event:
              type: string
              format: date-time
            newest_event:
              type: string
              format: date-time
            indexes:
              type: array
              items:
                $ref: '#/components/schemas/Index'
            jobs:
              type: object
              properties:
                running:
                  type: integer
                done:
                  type: integer
                error:
                  type: integer
                canceled:
                  type: integer
    ConfigPatchResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            config:
              type: object
            restart_required:
              type: array
              items:
                type: string
    CreateKeyRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        scope:
          type: string
          enum: [ingest, query, admin, full]
          default: full
        expires_in:
          type: string
          description: Go duration (`720h`), `30d`, `4w`, `1y`, or `never`
        description:
          type: string
    APIKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
        scope:
          type: string
        description:
          type: string
        expires_at:
          type: string
          format: date-time
          description: '`0001-01-01T00:00:00Z` for a key that does not expire'
        is_root:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
    CreatedKeyResponse:
      type: object
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/APIKey'
            - type: object
              properties:
                token:
                  type: string
                api_key:
                  type: string
                  description: '`id:token`, for the `ApiKey` scheme'
    KeyListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            keys:
              type: array
              items:
                $ref: '#/components/schemas/APIKey'
    RotateRootResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            prefix:
              type: string
            token:
              type: string
            is_root:
              type: boolean
            created_at:
              type: string
              format: date-time
            revoked_key_id:
              type: string
