#@ load("openapi.lib.yml", "response", "reference", "type", "array")

paths:
  /:
    get:
      summary: Returns information about the running Qdrant instance
      description: Returns information about the running Qdrant instance like version and commit id
      operationId: root
      tags:
        - Service
      responses:
        "200":
          description: Qdrant server version information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionInfo"
        "4XX":
          description: error

  /telemetry:
    get:
      summary: Collect telemetry data
      description: Collect telemetry data including app info, system info, collections info, cluster info, configs and statistics
      operationId: telemetry
      tags:
        - Service
      parameters:
        - name: anonymize
          in: query
          description: "If true, anonymize result"
          required: false
          schema:
            type: boolean
        - name: details_level
          in: query
          description: "Level of details in telemetry data. Minimal level is 0, maximal is infinity"
          required: false
          schema:
            type: integer
            minimum: 0
        - name: per_collection
          in: query
          description: "If true, include per-collection request statistics in the response"
          required: false
          schema:
            type: boolean
        - name: timeout
          in: query
          description: "Timeout for this request"
          required: false
          schema:
            type: integer
            minimum: 1
            default: 60 #! Keep in sync with DEFAULT_TELEMETRY_TIMEOUT
      responses: #@ response(reference("TelemetryData"))

  /metrics:
    get:
      summary: Collect Prometheus metrics data
      description: Collect metrics data including app info, collections info, cluster info and statistics
      operationId: metrics
      tags:
        - Service
      parameters:
        - name: anonymize
          in: query
          description: "If true, anonymize result"
          required: false
          schema:
            type: boolean
        - name: per_collection
          in: query
          description: "If true, include per-collection request metrics with a collection label instead of global request metrics"
          required: false
          schema:
            type: boolean
        - name: timeout
          in: query
          description: "Timeout for this request"
          required: false
          schema:
            type: integer
            minimum: 1
            default: 60 #! Keep in sync with DEFAULT_TELEMETRY_TIMEOUT
      responses:
        "200":
          description: Metrics data in Prometheus format
          content:
            text/plain:
              schema:
                type: string
                example: |
                  # HELP app_info information about qdrant server
                  # TYPE app_info gauge
                  app_info{name="qdrant",version="0.11.1"} 1
                  # HELP cluster_enabled is cluster support enabled
                  # TYPE cluster_enabled gauge
                  cluster_enabled 0
                  # HELP collections_total number of collections
                  # TYPE collections_total gauge
                  collections_total 1
        "4XX":
          description: error

  /healthz:
    get:
      summary: Kubernetes healthz endpoint
      description: >-
        Liveness-style health check. Returns 200 as soon as the HTTP API is
        serving requests. It does not inspect collections, shards or consensus
        state, and is identical to `/livez`. Use it only to detect whether the
        process is up and responsive.
      operationId: healthz
      tags:
        - Service
      responses:
        "200":
          description: Healthz response
          content:
            text/plain:
              schema:
                type: string
                example: healthz check passed
        "4XX":
          description: error

  /livez:
    get:
      summary: Kubernetes livez endpoint
      description: >-
        Kubernetes liveness probe. Returns 200 as soon as the HTTP API is
        serving requests. It does not inspect collections, shards or consensus
        state, and is identical to `/healthz`. A failure indicates the process
        is unresponsive and should be restarted.
      operationId: livez
      tags:
        - Service
      responses:
        "200":
          description: Healthz response
          content:
            text/plain:
              schema:
                type: string
                example: healthz check passed
        "4XX":
          description: error

  /readyz:
    get:
      summary: Kubernetes readyz endpoint
      description: >-
        Kubernetes readiness probe. Checks the instance and waits out pending
        data operations to see when it can start accepting traffic. In a
        distributed deployment it returns 200 only once the node has caught up
        with the cluster consensus commit and its local shards are healthy;
        otherwise it returns 503. In a single-node deployment it always returns
        200 once the API is up. Use it to decide when to route traffic to the
        instance.
      operationId: readyz
      tags:
        - Service
      responses:
        "200":
          description: The instance is ready to accept traffic
          content:
            text/plain:
              schema:
                type: string
                example: all shards are ready
        "503":
          description: The instance is not ready to accept traffic yet
          content:
            text/plain:
              schema:
                type: string
                example: some shards are not ready
        "4XX":
          description: error

  /issues:
    get:
      summary: Get issues
      description: Get a report of performance issues and configuration suggestions
      operationId: get_issues
      tags:
        - Beta
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        "4XX":
          description: error
    delete:
      summary: Clear issues
      description: Removes all issues reported so far
      operationId: clear_issues
      tags:
        - Beta
      responses: #@ response(type("boolean"))