openapi.yaml

openapi: 3.0.1
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`, `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 POST 'http://localhost:6333/collections' \
      -H 'Content-Type: application/json' \
      --data-raw '{
          "create_collection": {
              "name": "test_collection",
              "vector_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": {
        "vectors_count": 0,
        "segments_count": 5,
        "disk_data_size": 0,
        "ram_data_size": 0,
        "config": {
          "vector_size": 4,
          "index": {
            "type": "plain",
            "options": {}
          },
          "distance": "Dot",
          "storage_type": {
            "type": "in_memory"
          }
        }
      },
      "status": "ok",
      "time": 2.1199e-05
    }

    ```


    ### Add points

    Let's now add vectors with some payload:

    ```

    curl -L -X POST 'http://localhost:6333/collections/test_collection?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
      "upsert_points": {
        "points": [
          {"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": {"type": "keyword", "value": "Berlin"}}},
          {"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": {"type": "keyword", "value": ["Berlin", "London"] }}},
          {"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": {"type": "keyword", "value": ["Berlin", "Moscow"] }}},
          {"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": {"type": "keyword", "value": ["London", "Moscow"]}}},
          {"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": {"type": "integer", "value": [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 },
            { "id": 1, "score": 1.273 },
            { "id": 3, "score": 1.208 }
        ],
        "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": {
                        "keyword": "London"
                    }
                }
            ]
        },
        "vector": [0.2, 0.1, 0.9, 0.7],
        "top": 3
    }'

    ```

    Expected response:

    ```

    {
        "result": [
            { "id": 4, "score": 1.362 },
            { "id": 2, "score": 0.871 }
        ],
        "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: 0.2.1
externalDocs:
  description: Find out more about Qdrant aplications and demo
  url: demo.qdrant.tech
servers:
  - url: http://localhost:6333
tags:
  - name: collections
    description: Searchable collections of points.
  - name: points
    description: Float-point vectors with payload.

paths:
  /collections:
    get:
      tags:
        - collections
      summary: Get list of existing collections
      operationId: get_collections
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    $ref: "./models.json#/components/schemas/CollectionsResponse"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      tags:
        - collections
      summary: Perform update operation on collections
      operationId: update_collections
      requestBody:
        description: Operation to perform on collections
        content:
          application/json:
            schema:
              $ref: "./models.json#/components/schemas/StorageOperations"
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    type: boolean
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collections/{name}:
    get:
      tags:
        - collections
      summary: Get information about existing collection
      operationId: get_collection
      parameters:
        - name: name
          in: path
          description: Name of the collection to retrieve
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    $ref: "./models.json#/components/schemas/CollectionInfo"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      tags:
        - points
      summary: Update points (vectors, payloads, indexes) in collection
      operationId: update_points
      requestBody:
        description: Collection update operations
        content:
          application/json:
            schema:
              $ref: "./models.json#/components/schemas/CollectionUpdateOperations"

      parameters:
        - name: name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "Wait for changes to actually happen? Default: false"
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: [ "ok" ]
                  result:
                    $ref: "./models.json#/components/schemas/UpdateResult"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"


  /collections/{name}/points/{id}:
    get:
      tags:
        - points
      summary: Retrieve point by id
      operationId: get_point
      parameters:
        - name: name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Id of the point
          required: true
          schema:
            type: integer
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    $ref: "./models.json#/components/schemas/Record"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collections/{name}/points:
    post:
      tags:
        - points
      summary: Retrieve points by ids
      operationId: get_points
      requestBody:
        description: List of points to retrieve
        content:
          application/json:
            schema:
              $ref: "./models.json#/components/schemas/PointRequest"

      parameters:
        - name: name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    type: array
                    items:
                      $ref: "./models.json#/components/schemas/Record"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collections/{name}/points/search:
    post:
      tags:
        - points
      summary: Search points
      operationId: search_points
      requestBody:
        description: Search request with optional filtering
        content:
          application/json:
            schema:
              $ref: "./models.json#/components/schemas/SearchRequest"

      parameters:
        - name: name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    type: array
                    items:
                      $ref: "./models.json#/components/schemas/ScoredPoint"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collections/{name}/points/recommend:
    post:
      tags:
        - points
      summary: Recommend points
      operationId: recommend_points
      requestBody:
        description: Request points based on positive and negative examples.
        content:
          application/json:
            schema:
              $ref: "./models.json#/components/schemas/RecommendRequest"

      parameters:
        - name: name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                  status:
                    type: string
                    enum: ["ok"]
                  result:
                    type: array
                    items:
                      $ref: "./models.json#/components/schemas/ScoredPoint"
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"


components:
  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