#@ 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/search:
    post:
      deprecated: true
      tags:
        - Search
      summary: Search points
      description: Retrieve closest points based on vector similarity and given filtering conditions
      operationId: search_points
      requestBody:
        description: Search request with optional filtering
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"

      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(array(reference("ScoredPoint")))

  /collections/{collection_name}/points/search/batch:
    post:
      deprecated: true
      tags:
        - Search
      summary: Search batch points
      description: Retrieve by batch the closest points based on vector similarity and given filtering conditions
      operationId: search_batch_points
      requestBody:
        description: Search batch request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequestBatch"

      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(array(array(reference("ScoredPoint"))))

  /collections/{collection_name}/points/search/groups:
    post:
      deprecated: true
      tags:
        - Search
      summary: Search point groups
      description: Retrieve closest points based on vector similarity and given filtering conditions, grouped by a given payload field
      operationId: search_point_groups
      requestBody:
        description: Search request with optional filtering, grouped by a given payload field
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchGroupsRequest"

      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("GroupsResult"))

  /collections/{collection_name}/points/recommend:
    post:
      deprecated: true
      tags:
        - Search
      summary: Recommend points
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
      operationId: recommend_points
      requestBody:
        description: Request points based on positive and negative examples.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendRequest"

      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(array(reference("ScoredPoint")))

  /collections/{collection_name}/points/recommend/batch:
    post:
      deprecated: true
      tags:
        - Search
      summary: Recommend batch points
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
      operationId: recommend_batch_points
      requestBody:
        description: Request points based on positive and negative examples.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendRequestBatch"

      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(array(array(reference("ScoredPoint"))))

  /collections/{collection_name}/points/recommend/groups:
    post:
      deprecated: true
      tags:
        - Search
      summary: Recommend point groups
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples, grouped by a given payload field.
      operationId: recommend_point_groups
      requestBody:
        description: Request points based on positive and negative examples, grouped by a payload field.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendGroupsRequest"

      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("GroupsResult"))

  /collections/{collection_name}/points/discover:
    post:
      deprecated: true
      tags:
        - Search
      summary: Discover points
      description: >
        Use context and a target to find the most similar points to the target, constrained by the context.

        When using only the context (without a target), a special search - called context search - is performed where
        pairs of points are used to generate a loss that guides the search towards the zone where
        most positive examples overlap. This means that the score minimizes the scenario of
        finding a point closer to a negative than to a positive part of a pair.

        Since the score of a context relates to loss, the maximum score a point can get is 0.0,
        and it becomes normal that many points can have a score of 0.0.

        When using target (with or without context), the score behaves a little different: The
        integer part of the score represents the rank with respect to the context, while the
        decimal part of the score relates to the distance to the target. The context part of the score for
        each pair is calculated +1 if the point is closer to a positive than to a negative part of a pair,
        and -1 otherwise.
      operationId: discover_points
      requestBody:
        description: Request points based on {positive, negative} pairs of examples, and/or a target
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DiscoverRequest"

      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(array(reference("ScoredPoint")))

  /collections/{collection_name}/points/discover/batch:
    post:
      deprecated: true
      tags:
        - Search
      summary: Discover batch points
      description: Look for points based on target and/or positive and negative example pairs, in batch.
      operationId: discover_batch_points
      requestBody:
        description: Batch request points based on { positive, negative } pairs of examples, and/or a target.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DiscoverRequestBatch"

      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(array(array(reference("ScoredPoint"))))

  /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