openapi: 3.0.1
info:
  title: Qdrant Aliases 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: Aliases
  description: Additional names for existing collections.
paths:
  /collections/aliases:
    post:
      tags:
      - Aliases
      summary: Update aliases of the collections
      operationId: update_aliases
      requestBody:
        description: Alias update operations
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeAliasesOperation'
      parameters:
      - name: timeout
        in: query
        description: 'Wait for operation commit timeout in seconds.

          If timeout is reached - request will return with service error.

          '
        schema:
          type: integer
      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:
                    type: boolean
  /collections/{collection_name}/aliases:
    get:
      tags:
      - Aliases
      summary: List aliases for collection
      description: Get list of all aliases for a collection
      operationId: get_collection_aliases
      parameters:
      - name: collection_name
        in: path
        description: Name of the collection
        required: true
        schema:
          type: string
      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/CollectionsAliasesResponse'
  /aliases:
    get:
      tags:
      - Aliases
      summary: List collections aliases
      description: Get list of all existing collections aliases
      operationId: get_collections_aliases
      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/CollectionsAliasesResponse'
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
    AliasOperations:
      description: Group of all the possible operations related to collection aliases
      anyOf:
      - $ref: '#/components/schemas/CreateAliasOperation'
      - $ref: '#/components/schemas/DeleteAliasOperation'
      - $ref: '#/components/schemas/RenameAliasOperation'
    CreateAliasOperation:
      type: object
      required:
      - create_alias
      properties:
        create_alias:
          $ref: '#/components/schemas/CreateAlias'
    DeleteAlias:
      description: Delete alias if exists
      type: object
      required:
      - alias_name
      properties:
        alias_name:
          type: string
    RenameAlias:
      description: Change alias to a new one
      type: object
      required:
      - new_alias_name
      - old_alias_name
      properties:
        old_alias_name:
          type: string
        new_alias_name:
          type: string
    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
    AliasDescription:
      type: object
      required:
      - alias_name
      - collection_name
      properties:
        alias_name:
          type: string
        collection_name:
          type: string
      example:
        alias_name: blogs-title
        collection_name: arivx-title
    RenameAliasOperation:
      description: Change alias to a new one
      type: object
      required:
      - rename_alias
      properties:
        rename_alias:
          $ref: '#/components/schemas/RenameAlias'
    CreateAlias:
      description: Create alternative name for a collection. Collection will be available under both names for search, retrieve,
      type: object
      required:
      - alias_name
      - collection_name
      properties:
        collection_name:
          type: string
        alias_name:
          type: string
    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
    InferenceUsage:
      type: object
      required:
      - models
      properties:
        models:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelUsage'
    ModelUsage:
      type: object
      required:
      - tokens
      properties:
        tokens:
          type: integer
          format: uint64
          minimum: 0
    DeleteAliasOperation:
      description: Delete alias if exists
      type: object
      required:
      - delete_alias
      properties:
        delete_alias:
          $ref: '#/components/schemas/DeleteAlias'
    CollectionsAliasesResponse:
      type: object
      required:
      - aliases
      properties:
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/AliasDescription'
    ChangeAliasesOperation:
      description: Operation for performing changes of collection aliases. Alias changes are atomic, meaning that no collection modifications can happen between alias operations.
      type: object
      required:
      - actions
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AliasOperations'
  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/