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

openapi: 3.0.1
security:
  - api-key: []
  - bearerAuth: []
  - {}
info:
  title: Qdrant API
  description: >
    API description for Qdrant vector search engine.


    This document describes CRUD and search operations on collections of points (vectors with payload).


    Qdrant supports any combinations of `should`, `min_should`, `must` and `must_not` conditions,
    which makes it possible to use in applications when object could not be described solely by vector.
    It could be location features, availability flags, and other custom properties businesses should take into account.

    ## Examples

    This examples cover the most basic use-cases - collection creation and basic vector search.

    ### Create collection

    First - let's create a collection with dot-production metric.

    ```

    curl -X PUT 'http://localhost:6333/collections/test_collection' \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "vectors": {
          "size": 4,
          "distance": "Dot"
        }
      }'

    ```

    Expected response:

    ```

    {
        "result": true,
        "status": "ok",
        "time": 0.031095451
    }

    ```

    We can ensure that collection was created:

    ```

    curl 'http://localhost:6333/collections/test_collection'

    ```

    Expected response:

    ```

    {
      "result": {
        "status": "green",
        "segments_count": 5,
        "disk_data_size": 0,
        "ram_data_size": 0,
        "config": {
          "params": {
            "vectors": {
              "size": 4,
              "distance": "Dot"
            }
          },
          "hnsw_config": {
            "m": 16,
            "ef_construct": 100,
            "full_scan_threshold": 10000
          },
          "optimizer_config": {
            "deleted_threshold": 0.2,
            "vacuum_min_vector_number": 1000,
            "default_segment_number": 2,
            "max_segment_size": null,
            "memmap_threshold": null,
            "indexing_threshold": 20000,
            "flush_interval_sec": 5,
            "max_optimization_threads": null
          },
          "wal_config": {
            "wal_capacity_mb": 32,
            "wal_segments_ahead": 0
          }
        }
      },
      "status": "ok",
      "time": 2.1199e-05
    }

    ```


    ### Add points

    Let's now add vectors with some payload:

    ```

    curl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
      "points": [
        {"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": "Berlin"}},
        {"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": ["Berlin", "London"] }},
        {"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": ["Berlin", "Moscow"] }},
        {"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": ["London", "Moscow"] }},
        {"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": [0]}},
        {"id": 6, "vector": [0.35, 0.08, 0.11, 0.44]}
      ]
    }'

    ```

    Expected response:

    ```

    {
        "result": {
            "operation_id": 0,
            "status": "completed"
        },
        "status": "ok",
        "time": 0.000206061
    }

    ```

    ### Search with filtering

    Let's start with a basic request:

    ```

    curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "vector": [0.2,0.1,0.9,0.7],
        "top": 3
    }'

    ```

    Expected response:

    ```

    {
        "result": [
            { "id": 4, "score": 1.362, "payload": null, "version": 0 },
            { "id": 1, "score": 1.273, "payload": null, "version": 0 },
            { "id": 3, "score": 1.208, "payload": null, "version": 0 }
        ],
        "status": "ok",
        "time": 0.000055785
    }

    ```

    But result is different if we add a filter:

    ```

    curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "filter": {
            "should": [
                {
                    "key": "city",
                    "match": {
                        "value": "London"
                    }
                }
            ]
        },
        "vector": [0.2, 0.1, 0.9, 0.7],
        "top": 3
    }'

    ```

    Expected response:

    ```

    {
        "result": [
            { "id": 4, "score": 1.362, "payload": null, "version": 0 },
            { "id": 2, "score": 0.871, "payload": null, "version": 0 }
        ],
        "status": "ok",
        "time": 0.000093972
    }

    ```

  contact:
    email: andrey@vasnetsov.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: master
externalDocs:
  description: Find out more about Qdrant applications and demo
  url: https://qdrant.tech/documentation/
servers:
  - url: "{protocol}://{hostname}:{port}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      hostname:
        default: localhost
      port:
        default: "6333"
tags:
  - name: Collections
    description: Searchable collections of points.
  - name: Points
    description: Float-point vectors with payload.
  - name: Search
    description: Find points in a collection.
  - name: Aliases
    description: Additional names for existing collections.
  - name: Indexes
    description: Indexes for payloads associated with points.
  - name: Distributed
    description: Service distributed setup.
  - name: Snapshots
    description: Storage and collections snapshots.
  - name: Service
    description: Qdrant service utilities.
  - name: Beta
    description: Beta features, do not depend on these yet.

paths:
  /collections/{collection_name}/points/scroll:
    post:
      tags:
        - Points
      summary: Scroll points
      description: Scroll request - paginate over all points which matches given filtering condition
      operationId: scroll_points
      requestBody:
        description: Pagination and filter parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScrollRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("ScrollResult"))

  /collections/{collection_name}/points/count:
    post:
      tags:
        - Points
      summary: Count points
      description: Count points which matches given filtering condition
      operationId: count_points
      requestBody:
        description: Request counts of points which matches given filtering condition
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CountRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to count in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("CountResult"))

  /collections/{collection_name}/facet:
    post:
      tags:
        - Points
      summary: Facet a payload key with a given filter.
      description: Count points that satisfy the given filter for each unique value of a payload key.
      operationId: facet
      requestBody:
        description: Request counts of points for each unique value of a payload key
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FacetRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to facet in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("FacetResponse"))

  /collections/{collection_name}/points/query:
    post:
      tags:
        - Search
      summary: Query points
      description: Universally query points. This endpoint covers all capabilities of search, recommend, discover, filters. But also enables hybrid and multi-stage queries.
      operationId: query_points
      requestBody:
        description: Describes the query to make to the collection
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequest"


      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to query
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1

      responses: #@ response(reference("QueryResponse"))

  /collections/{collection_name}/points/query/batch:
    post:
      tags:
        - Search
      summary: Query points in batch
      description: Universally query points in batch. This endpoint covers all capabilities of search, recommend, discover, filters. But also enables hybrid and multi-stage queries.
      operationId: query_batch_points
      requestBody:
        description: Describes the queries to make to the collection
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequestBatch"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to query
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1

      responses: #@ response(array(reference("QueryResponse")))

  /collections/{collection_name}/points/query/groups:
    post:
      tags:
        - Search
      summary: Query points, grouped by a given payload field
      description: Universally query points, grouped by a given payload field
      operationId: query_points_groups
      requestBody:
        description: Describes the query to make to the collection
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryGroupsRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to query
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1

      responses: #@ response(reference("GroupsResult"))

  /collections/{collection_name}/points/search/matrix/pairs:
    post:
      tags:
        - Search
      summary: Search points matrix distance pairs
      description: Compute distance matrix for sampled points with a pair based output format
      operationId: search_matrix_pairs
      requestBody:
        description: Search matrix request with optional filtering
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchMatrixRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("SearchMatrixPairsResponse"))

  /collections/{collection_name}/points/search/matrix/offsets:
    post:
      tags:
        - Search
      summary: Search points matrix distance offsets
      description: Compute distance matrix for sampled points with an offset based output format
      operationId: search_matrix_offsets
      requestBody:
        description: Search matrix request with optional filtering
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchMatrixRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
        - name: timeout
          in: query
          description: If set, overrides global timeout for this request. Unit is seconds.
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("SearchMatrixOffsetsResponse"))

components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: Authorization key, either read-write or read-only
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    ErrorResponse:
      type: object
      properties:
        time:
          type: number
          format: float
          description: Time spent to process this request
        status:
          type: object
          properties:
            error:
              type: string
              description: Description of the occurred error.
        result:
          type: object
          nullable: true