openapi: 3.0.1
info:
  title: Qdrant Aliases Indexes API
  description: "API description for Qdrant vector search engine.\n\nThis document describes CRUD and search operations on collections of points (vectors with payload).\n\nQdrant 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.\n## Examples\nThis examples cover the most basic use-cases - collection creation and basic vector search.\n### Create collection\nFirst - let's create a collection with dot-production metric.\n```\ncurl -X PUT 'http://localhost:6333/collections/test_collection' \\\n  -H 'Content-Type: application/json' \\\n  --data-raw '{\n    \"vectors\": {\n      \"size\": 4,\n      \"distance\": \"Dot\"\n    }\n  }'\n\n```\nExpected response:\n```\n{\n    \"result\": true,\n    \"status\": \"ok\",\n    \"time\": 0.031095451\n}\n```\nWe can ensure that collection was created:\n```\ncurl 'http://localhost:6333/collections/test_collection'\n```\nExpected response:\n```\n{\n  \"result\": {\n    \"status\": \"green\",\n    \"segments_count\": 5,\n    \"disk_data_size\": 0,\n    \"ram_data_size\": 0,\n    \"config\": {\n      \"params\": {\n        \"vectors\": {\n          \"size\": 4,\n          \"distance\": \"Dot\"\n        }\n      },\n      \"hnsw_config\": {\n        \"m\": 16,\n        \"ef_construct\": 100,\n        \"full_scan_threshold\": 10000\n      },\n      \"optimizer_config\": {\n        \"deleted_threshold\": 0.2,\n        \"vacuum_min_vector_number\": 1000,\n        \"default_segment_number\": 2,\n        \"max_segment_size\": null,\n        \"memmap_threshold\": null,\n        \"indexing_threshold\": 20000,\n        \"flush_interval_sec\": 5,\n        \"max_optimization_threads\": null\n      },\n      \"wal_config\": {\n        \"wal_capacity_mb\": 32,\n        \"wal_segments_ahead\": 0\n      }\n    }\n  },\n  \"status\": \"ok\",\n  \"time\": 2.1199e-05\n}\n```\n\n### Add points\nLet's now add vectors with some payload:\n```\ncurl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n  \"points\": [\n    {\"id\": 1, \"vector\": [0.05, 0.61, 0.76, 0.74], \"payload\": {\"city\": \"Berlin\"}},\n    {\"id\": 2, \"vector\": [0.19, 0.81, 0.75, 0.11], \"payload\": {\"city\": [\"Berlin\", \"London\"] }},\n    {\"id\": 3, \"vector\": [0.36, 0.55, 0.47, 0.94], \"payload\": {\"city\": [\"Berlin\", \"Moscow\"] }},\n    {\"id\": 4, \"vector\": [0.18, 0.01, 0.85, 0.80], \"payload\": {\"city\": [\"London\", \"Moscow\"] }},\n    {\"id\": 5, \"vector\": [0.24, 0.18, 0.22, 0.44], \"payload\": {\"count\": [0]}},\n    {\"id\": 6, \"vector\": [0.35, 0.08, 0.11, 0.44]}\n  ]\n}'\n```\nExpected response:\n```\n{\n    \"result\": {\n        \"operation_id\": 0,\n        \"status\": \"completed\"\n    },\n    \"status\": \"ok\",\n    \"time\": 0.000206061\n}\n```\n### Search with filtering\nLet's start with a basic request:\n```\ncurl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n    \"vector\": [0.2,0.1,0.9,0.7],\n    \"top\": 3\n}'\n```\nExpected response:\n```\n{\n    \"result\": [\n        { \"id\": 4, \"score\": 1.362, \"payload\": null, \"version\": 0 },\n        { \"id\": 1, \"score\": 1.273, \"payload\": null, \"version\": 0 },\n        { \"id\": 3, \"score\": 1.208, \"payload\": null, \"version\": 0 }\n    ],\n    \"status\": \"ok\",\n    \"time\": 0.000055785\n}\n```\nBut result is different if we add a filter:\n```\ncurl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n    \"filter\": {\n        \"should\": [\n            {\n                \"key\": \"city\",\n                \"match\": {\n                    \"value\": \"London\"\n                }\n            }\n        ]\n    },\n    \"vector\": [0.2, 0.1, 0.9, 0.7],\n    \"top\": 3\n}'\n```\nExpected response:\n```\n{\n    \"result\": [\n        { \"id\": 4, \"score\": 1.362, \"payload\": null, \"version\": 0 },\n        { \"id\": 2, \"score\": 0.871, \"payload\": null, \"version\": 0 }\n    ],\n    \"status\": \"ok\",\n    \"time\": 0.000093972\n}\n```\n"
  contact:
    email: andrey@vasnetsov.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: master
servers:
- url: '{protocol}://{hostname}:{port}'
  variables:
    protocol:
      enum:
      - http
      - https
      default: http
    hostname:
      default: localhost
    port:
      default: '6333'
security:
- api-key: []
- bearerAuth: []
- {}
tags:
- name: Indexes
  description: Indexes for payloads associated with points.
paths:
  /collections/{collection_name}/index:
    put:
      tags:
      - Indexes
      summary: Create index for field in collection
      description: Create index for field in collection
      operationId: create_field_index
      parameters:
      - name: collection_name
        in: path
        description: Name of the collection
        required: true
        schema:
          type: string
      - name: wait
        in: query
        description: If true, wait for changes to actually happen
        required: false
        schema:
          type: boolean
      - name: ordering
        in: query
        description: define ordering guarantees for the operation
        required: false
        schema:
          $ref: '#/components/schemas/WriteOrdering'
      - name: timeout
        in: query
        description: Timeout for the operation
        required: false
        schema:
          type: integer
          minimum: 1
      requestBody:
        description: Field name
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFieldIndex'
      responses:
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        4XX:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    default: null
                    anyOf:
                    - $ref: '#/components/schemas/Usage'
                    - nullable: true
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                    example: 0.002
                  status:
                    type: string
                    example: ok
                  result:
                    $ref: '#/components/schemas/UpdateResult'
  /collections/{collection_name}/index/{field_name}:
    delete:
      tags:
      - Indexes
      summary: Delete index for field in collection
      description: Delete field index for collection
      operationId: delete_field_index
      parameters:
      - name: collection_name
        in: path
        description: Name of the collection
        required: true
        schema:
          type: string
      - name: field_name
        in: path
        description: Name of the field where to delete the index
        required: true
        schema:
          type: string
      - name: wait
        in: query
        description: If true, wait for changes to actually happen
        required: false
        schema:
          type: boolean
      - name: ordering
        in: query
        description: define ordering guarantees for the operation
        required: false
        schema:
          $ref: '#/components/schemas/WriteOrdering'
      - name: timeout
        in: query
        description: Timeout for the operation
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        4XX:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    default: null
                    anyOf:
                    - $ref: '#/components/schemas/Usage'
                    - nullable: true
                  time:
                    type: number
                    format: float
                    description: Time spent to process this request
                    example: 0.002
                  status:
                    type: string
                    example: ok
                  result:
                    $ref: '#/components/schemas/UpdateResult'
components:
  schemas:
    HardwareUsage:
      description: Usage of the hardware resources, spent to process the request
      type: object
      required:
      - cpu
      - payload_index_io_read
      - payload_index_io_write
      - payload_io_read
      - payload_io_write
      - vector_io_read
      - vector_io_write
      properties:
        cpu:
          type: integer
          format: uint
          minimum: 0
        payload_io_read:
          type: integer
          format: uint
          minimum: 0
        payload_io_write:
          type: integer
          format: uint
          minimum: 0
        payload_index_io_read:
          type: integer
          format: uint
          minimum: 0
        payload_index_io_write:
          type: integer
          format: uint
          minimum: 0
        vector_io_read:
          type: integer
          format: uint
          minimum: 0
        vector_io_write:
          type: integer
          format: uint
          minimum: 0
    KeywordIndexType:
      type: string
      enum:
      - keyword
    TextIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/TextIndexType'
        tokenizer:
          $ref: '#/components/schemas/TokenizerType'
        min_token_len:
          description: Minimum characters to be tokenized.
          type: integer
          format: uint
          minimum: 0
          nullable: true
        max_token_len:
          description: Maximum characters to be tokenized.
          type: integer
          format: uint
          minimum: 0
          nullable: true
        lowercase:
          description: 'If true, lowercase all tokens. Default: true.'
          type: boolean
          nullable: true
        ascii_folding:
          description: 'If true, normalize tokens by folding accented characters to ASCII (e.g., "ação" -> "acao"). Default: false.'
          type: boolean
          nullable: true
        phrase_matching:
          description: 'If true, support phrase matching. Default: false.'
          type: boolean
          nullable: true
        stopwords:
          description: Ignore this set of tokens. Can select from predefined languages and/or provide a custom set.
          anyOf:
          - $ref: '#/components/schemas/StopwordsInterface'
          - nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        stemmer:
          description: 'Algorithm for stemming. Default: disabled.'
          anyOf:
          - $ref: '#/components/schemas/StemmingAlgorithm'
          - nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    TokenizerType:
      type: string
      enum:
      - prefix
      - whitespace
      - word
      - multilingual
    GeoIndexType:
      type: string
      enum:
      - geo
    DatetimeIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/DatetimeIndexType'
        is_principal:
          description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests.
          type: boolean
          nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    Snowball:
      type: string
      enum:
      - snowball
    UuidIndexType:
      type: string
      enum:
      - uuid
    TextIndexType:
      type: string
      enum:
      - text
    Usage:
      description: Usage of the hardware resources, spent to process the request
      type: object
      properties:
        hardware:
          anyOf:
          - $ref: '#/components/schemas/HardwareUsage'
          - nullable: true
        inference:
          anyOf:
          - $ref: '#/components/schemas/InferenceUsage'
          - nullable: true
    DatetimeIndexType:
      type: string
      enum:
      - datetime
    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
    BoolIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/BoolIndexType'
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    InferenceUsage:
      type: object
      required:
      - models
      properties:
        models:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelUsage'
    KeywordIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/KeywordIndexType'
        is_tenant:
          description: 'If true - used for tenant optimization. Default: false.'
          type: boolean
          nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    StopwordsSet:
      type: object
      properties:
        languages:
          description: Set of languages to use for stopwords. Multiple pre-defined lists of stopwords can be combined.
          type: array
          items:
            $ref: '#/components/schemas/Language'
          uniqueItems: true
          nullable: true
        custom:
          description: Custom stopwords set. Will be merged with the languages set.
          type: array
          items:
            type: string
          uniqueItems: true
          nullable: true
    SnowballLanguage:
      description: Languages supported by snowball stemmer.
      type: string
      enum:
      - arabic
      - armenian
      - danish
      - dutch
      - english
      - finnish
      - french
      - german
      - greek
      - hungarian
      - italian
      - norwegian
      - portuguese
      - romanian
      - russian
      - spanish
      - swedish
      - tamil
      - turkish
    IntegerIndexType:
      type: string
      enum:
      - integer
    CreateFieldIndex:
      type: object
      required:
      - field_name
      properties:
        field_name:
          type: string
        field_schema:
          anyOf:
          - $ref: '#/components/schemas/PayloadFieldSchema'
          - nullable: true
    IntegerIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/IntegerIndexType'
        lookup:
          description: If true - support direct lookups. Default is true.
          type: boolean
          nullable: true
        range:
          description: If true - support ranges filters. Default is true.
          type: boolean
          nullable: true
        is_principal:
          description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests. Default is false.
          type: boolean
          nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false. Default is false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    WriteOrdering:
      description: 'Defines write ordering guarantees for collection operations


        * `weak` - write operations may be reordered, works faster, default


        * `medium` - write operations go through dynamically selected leader, may be inconsistent for a short period of time in case of leader change


        * `strong` - Write operations go through the permanent leader, consistent, but may be unavailable if leader is down'
      type: string
      enum:
      - weak
      - medium
      - strong
    UpdateStatus:
      description: '`Acknowledged` - Request is saved to WAL and will be process in a queue. `Completed` - Request is completed, changes are actual. `WaitTimeout` - Request is waiting for timeout.'
      type: string
      enum:
      - acknowledged
      - completed
      - wait_timeout
    PayloadFieldSchema:
      anyOf:
      - $ref: '#/components/schemas/PayloadSchemaType'
      - $ref: '#/components/schemas/PayloadSchemaParams'
    PayloadSchemaType:
      description: All possible names of payload types
      type: string
      enum:
      - keyword
      - integer
      - float
      - geo
      - text
      - bool
      - datetime
      - uuid
    UpdateResult:
      type: object
      required:
      - status
      properties:
        operation_id:
          description: Sequential number of the operation
          type: integer
          format: uint64
          minimum: 0
          nullable: true
        status:
          $ref: '#/components/schemas/UpdateStatus'
    StopwordsInterface:
      anyOf:
      - $ref: '#/components/schemas/Language'
      - $ref: '#/components/schemas/StopwordsSet'
    UuidIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/UuidIndexType'
        is_tenant:
          description: If true - used for tenant optimization.
          type: boolean
          nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    ModelUsage:
      type: object
      required:
      - tokens
      properties:
        tokens:
          type: integer
          format: uint64
          minimum: 0
    FloatIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/FloatIndexType'
        is_principal:
          description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests.
          type: boolean
          nullable: true
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    GeoIndexParams:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/GeoIndexType'
        on_disk:
          description: 'If true, store the index on disk. Default: false.'
          type: boolean
          nullable: true
        enable_hnsw:
          description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
          type: boolean
          nullable: true
    BoolIndexType:
      type: string
      enum:
      - bool
    PayloadSchemaParams:
      description: Payload type with parameters
      anyOf:
      - $ref: '#/components/schemas/KeywordIndexParams'
      - $ref: '#/components/schemas/IntegerIndexParams'
      - $ref: '#/components/schemas/FloatIndexParams'
      - $ref: '#/components/schemas/GeoIndexParams'
      - $ref: '#/components/schemas/TextIndexParams'
      - $ref: '#/components/schemas/BoolIndexParams'
      - $ref: '#/components/schemas/DatetimeIndexParams'
      - $ref: '#/components/schemas/UuidIndexParams'
    Language:
      type: string
      enum:
      - arabic
      - azerbaijani
      - basque
      - bengali
      - catalan
      - chinese
      - danish
      - dutch
      - english
      - finnish
      - french
      - german
      - greek
      - hebrew
      - hinglish
      - hungarian
      - indonesian
      - italian
      - japanese
      - kazakh
      - nepali
      - norwegian
      - portuguese
      - romanian
      - russian
      - slovene
      - spanish
      - swedish
      - tajik
      - turkish
    SnowballParams:
      type: object
      required:
      - language
      - type
      properties:
        type:
          $ref: '#/components/schemas/Snowball'
        language:
          $ref: '#/components/schemas/SnowballLanguage'
    StemmingAlgorithm:
      description: Different stemming algorithms with their configs.
      anyOf:
      - $ref: '#/components/schemas/SnowballParams'
    FloatIndexType:
      type: string
      enum:
      - float
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: Authorization key, either read-write or read-only
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Find out more about Qdrant applications and demo
  url: https://qdrant.tech/documentation/