openapi: 3.0.1
info:
title: Qdrant Aliases Search 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: Search
description: Find points in a collection.
paths:
/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:
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: array
items:
$ref: '#/components/schemas/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:
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: array
items:
type: array
items:
$ref: '#/components/schemas/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:
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/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:
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: array
items:
$ref: '#/components/schemas/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:
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: array
items:
type: array
items:
$ref: '#/components/schemas/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:
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/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:
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: array
items:
$ref: '#/components/schemas/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:
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: array
items:
type: array
items:
$ref: '#/components/schemas/ScoredPoint'
/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:
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/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:
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: array
items:
$ref: '#/components/schemas/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:
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/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:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: suc
# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qdrant/refs/heads/main/openapi/qdrant-search-api-openapi.yml