openapi: 3.0.1
info:
title: Qdrant Aliases Collections 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: Collections
description: Searchable collections of points.
paths:
/collections:
get:
tags:
- Collections
summary: List collections
description: Get list name of all existing collections
operationId: get_collections
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/CollectionsResponse'
/collections/{collection_name}:
get:
tags:
- Collections
summary: Collection info
description: Get detailed information about specified existing collection
operationId: get_collection
parameters:
- name: collection_name
in: path
description: Name of the collection to retrieve
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/CollectionInfo'
put:
tags:
- Collections
summary: Create collection
description: Create new collection with given parameters
operationId: create_collection
requestBody:
description: Parameters of a new collection
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollection'
parameters:
- name: collection_name
in: path
description: Name of the new collection
required: true
schema:
type: string
- 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
patch:
tags:
- Collections
summary: Update collection parameters
description: Update parameters of the existing collection
operationId: update_collection
requestBody:
description: New parameters
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCollection'
parameters:
- name: collection_name
in: path
description: Name of the collection to update
required: true
schema:
type: string
- 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
delete:
tags:
- Collections
summary: Delete collection
description: Drop collection and all associated data
operationId: delete_collection
parameters:
- name: collection_name
in: path
description: Name of the collection to delete
required: true
schema:
type: string
- 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}/exists:
get:
tags:
- Collections
summary: Check the existence of a collection
description: Returns "true" if the given collection name exists, and "false" otherwise
operationId: collection_exists
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/CollectionExistence'
/collections/{collection_name}/optimizations:
get:
tags:
- Collections
summary: Get optimization progress
description: Get progress of ongoing and completed optimizations for a collection
operationId: get_optimizations
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: with
in: query
description: 'Comma-separated list of optional fields to include in the response.
Possible values: queued, completed, idle_segments.'
required: false
schema:
type: string
- name: completed_limit
in: query
description: 'Maximum number of completed optimizations to return.
Ignored if `completed` is not in the `with` parameter.'
required: false
schema:
type: integer
minimum: 0
default: 16
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/OptimizationsResponse'
components:
schemas:
BinaryQuantization:
type: object
required:
- binary
properties:
binary:
$ref: '#/components/schemas/BinaryQuantizationConfig'
ProgressTree:
type: object
required:
- name
properties:
name:
description: Name of the operation.
type: string
started_at:
description: When the operation started.
type: string
format: date-time
nullable: true
finished_at:
description: When the operation finished.
type: string
format: date-time
nullable: true
duration_sec:
description: For finished operations, how long they took, in seconds.
type: number
format: double
nullable: true
done:
description: Number of completed units of work, if applicable.
type: integer
format: uint64
minimum: 0
nullable: true
total:
description: Total number of units of work, if applicable and known.
type: integer
format: uint64
minimum: 0
nullable: true
children:
description: Child operations.
type: array
items:
$ref: '#/components/schemas/ProgressTree'
PayloadIndexInfo:
description: Display payload field type & index information
type: object
required:
- data_type
- points
properties:
data_type:
$ref: '#/components/schemas/PayloadSchemaType'
params:
anyOf:
- $ref: '#/components/schemas/PayloadSchemaParams'
- nullable: true
points:
description: Number of points indexed with this index
type: integer
format: uint
minimum: 0
StrictModeConfigOutput:
type: object
properties:
enabled:
description: Whether strict mode is enabled for a collection or not.
type: boolean
nullable: true
max_query_limit:
description: Max allowed `limit` parameter for all APIs that don't have their own max limit.
type: integer
format: uint
minimum: 1
nullable: true
max_timeout:
description: Max allowed `timeout` parameter.
type: integer
format: uint
minimum: 1
nullable: true
unindexed_filtering_retrieve:
description: Allow usage of unindexed fields in retrieval based (e.g. search) filters.
type: boolean
nullable: true
unindexed_filtering_update:
description: Allow usage of unindexed fields in filtered updates (e.g. delete by payload).
type: boolean
nullable: true
search_max_hnsw_ef:
description: Max HNSW value allowed in search parameters.
type: integer
format: uint
minimum: 0
nullable: true
search_allow_exact:
description: Whether exact search is allowed or not.
type: boolean
nullable: true
search_max_oversampling:
description: Max oversampling value allowed in search.
type: number
format: double
nullable: true
upsert_max_batchsize:
description: Max batchsize when upserting
type: integer
format: uint
minimum: 0
nullable: true
search_max_batchsize:
description: Max batchsize when searching
type: integer
format: uint
minimum: 0
nullable: true
max_collection_vector_size_bytes:
description: Max size of a collections vector storage in bytes, ignoring replicas.
type: integer
format: uint
minimum: 0
nullable: true
read_rate_limit:
description: Max number of read operations per minute per replica
type: integer
format: uint
minimum: 0
nullable: true
write_rate_limit:
description: Max number of write operations per minute per replica
type: integer
format: uint
minimum: 0
nullable: true
max_collection_payload_size_bytes:
description: Max size of a collections payload storage in bytes
type: integer
format: uint
minimum: 0
nullable: true
max_points_count:
description: Max number of points estimated in a collection
type: integer
format: uint
minimum: 0
nullable: true
filter_max_conditions:
description: Max conditions a filter can have.
type: integer
format: uint
minimum: 0
nullable: true
condition_max_size:
description: Max size of a condition, eg. items in `MatchAny`.
type: integer
format: uint
minimum: 0
nullable: true
multivector_config:
description: Multivector configuration
anyOf:
- $ref: '#/components/schemas/StrictModeMultivectorConfigOutput'
- nullable: true
sparse_config:
description: Sparse vector configuration
anyOf:
- $ref: '#/components/schemas/StrictModeSparseConfigOutput'
- nullable: true
max_payload_index_count:
description: Max number of payload indexes in a collection
type: integer
format: uint
minimum: 0
nullable: true
GeoIndexType:
type: string
enum:
- geo
BinaryQuantizationEncoding:
type: string
enum:
- one_bit
- two_bits
- one_and_half_bits
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
Payload:
type: object
additionalProperties: true
example:
city: London
color: green
InferenceUsage:
type: object
required:
- models
properties:
models:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelUsage'
UpdateQueueInfo:
type: object
required:
- length
properties:
length:
description: Number of elements in the queue
type: integer
format: uint
minimum: 0
deferred_points:
description: Number of points that are deferred (i.e hidden from search as they're not yet optimized).
type: integer
format: uint
minimum: 0
nullable: true
PayloadSchemaType:
description: All possible names of payload types
type: string
enum:
- keyword
- integer
- float
- geo
- text
- bool
- datetime
- uuid
QuantizationConfig:
anyOf:
- $ref: '#/components/schemas/ScalarQuantization'
- $ref: '#/components/schemas/ProductQuantization'
- $ref: '#/components/schemas/BinaryQuantization'
CollectionsResponse:
type: object
required:
- collections
properties:
collections:
type: array
items:
$ref: '#/components/schemas/CollectionDescription'
example:
collections:
- name: arxiv-title
- name: arxiv-abstract
- name: medium-title
- name: medium-text
CreateCollection:
description: Operation for creating new collection and (optionally) specify index params
type: object
properties:
vectors:
$ref: '#/components/schemas/VectorsConfig'
shard_number:
description: 'For auto sharding: Number of shards in collection. - Default is 1 for standalone, otherwise equal to the number of nodes - Minimum is 1
For custom sharding: Number of shards in collection per shard group. - Default is 1, meaning that each shard key will be mapped to a single shard - Minimum is 1'
default: null
type: integer
format: uint32
minimum: 1
nullable: true
sharding_method:
description: Sharding method Default is Auto - points are distributed across all available shards Custom - points are distributed across shards according to shard key
default: null
anyOf:
- $ref: '#/components/schemas/ShardingMethod'
- nullable: true
replication_factor:
description: Number of shards replicas. Default is 1 Minimum is 1
default: null
type: integer
format: uint32
minimum: 1
nullable: true
write_consistency_factor:
description: Defines how many replicas should apply the operation for us to consider it successful. Increasing this number will make the collection more resilient to inconsistencies, but will also make it fail if not enough replicas are available. Does not have any performance impact.
default: null
type: integer
format: uint32
minimum: 1
nullable: true
on_disk_payload:
description: 'If true - point''s payload will not be stored in memory. It will be read from the disk every time it is requested. This setting saves RAM by (slightly) increasing the response time. Note: those payload values that are involved in filtering and are indexed - remain in RAM.
Default: true'
default: null
type: boolean
nullable: true
hnsw_config:
description: Custom params for HNSW index. If none - values from service configuration file are used.
anyOf:
- $ref: '#/components/schemas/HnswConfigDiff'
- nullable: true
wal_config:
description: Custom params for WAL. If none - values from service configuration file are used.
anyOf:
- $ref: '#/components/schemas/WalConfigDiff'
- nullable: true
optimizers_config:
description: Custom params for Optimizers. If none - values from service configuration file are used.
anyOf:
- $ref: '#/components/schemas/OptimizersConfigDiff'
- nullable: true
quantization_config:
description: Quantization parameters. If none - quantization is disabled.
default: null
anyOf:
- $ref: '#/components/schemas/QuantizationConfig'
- nullable: true
sparse_vectors:
description: Sparse vector data config.
type: object
additionalProperties:
$ref: '#/components/schemas/SparseVectorParams'
nullable: true
strict_mode_config:
description: Strict-mode config.
anyOf:
- $ref: '#/components/schemas/StrictModeConfig'
- nullable: true
metadata:
description: Arbitrary JSON metadata for the collection This can be used to store application-specific information such as creation time, migration data, inference model info, etc.
anyOf:
- $ref: '#/components/schemas/Payload'
- nullable: true
MaxOptimizationThreads:
anyOf:
- $ref: '#/components/schemas/MaxOptimizationThreadsSetting'
- type: integer
format: uint
minimum: 0
HnswConfig:
description: Config of HNSW index
type: object
required:
- ef_construct
- full_scan_threshold
- m
properties:
m:
description: Number of edges per node in the index graph. Larger the value - more accurate the search, more space required.
type: integer
format: uint
minimum: 0
ef_construct:
description: Number of neighbours to consider during the index building. Larger the value - more accurate the search, more time required to build index.
type: integer
format: uint
minimum: 4
full_scan_threshold:
description: 'Minimal size threshold (in KiloBytes) below which full-scan is preferred over HNSW search. This measures the total size of vectors being queried against. When the maximum estimated amount of points that a condition satisfies is smaller than `full_scan_threshold_kb`, the query planner will use full-scan search instead of HNSW index traversal for better performance. Note: 1Kb = 1 vector of size 256'
type: integer
format: uint
minimum: 0
max_indexing_threads:
description: Number of parallel threads used for background index building. If 0 - automatically select from 8 to 16. Best to keep between 8 and 16 to prevent likelihood of slow building or broken/inefficient HNSW graphs. On small CPUs, less threads are used.
default: 0
type: integer
format: uint
minimum: 0
on_disk:
description: 'Store HNSW index on disk. If set to false, index will be stored in RAM. Default: false'
type: boolean
nullable: true
payload_m:
description: Custom M param for hnsw graph built for payload index. If not set, default M will be used.
type: integer
format: uint
minimum: 0
nullable: true
inline_storage:
description: 'Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported.'
type: boolean
nullable: true
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
Disabled:
type: string
enum:
- Disabled
StrictModeMultivectorConfig:
type: object
additionalProperties:
$ref: '#/components/schemas/StrictModeMultivector'
BinaryQuantizationConfig:
type: object
properties:
always_ram:
type: boolean
nullable: true
encoding:
anyOf:
- $ref: '#/components/schemas/BinaryQuantizationEncoding'
- nullable: true
query_encoding:
description: Asymmetric quantization configuration allows a query to have different quantization than stored vectors. It can increase the accuracy of search at the cost of performance.
anyOf:
- $ref: '#/components/schemas/BinaryQuantizationQueryEncoding'
- nullable: true
StrictModeMultivectorConfigOutput:
type: object
additionalProperties:
$ref: '#/components/schemas/StrictModeMultivectorOutput'
ScalarQuantization:
type: object
required:
- scalar
properties:
scalar:
$ref: '#/components/schemas/ScalarQuantizationConfig'
FloatIndexType:
type: string
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qdrant/refs/heads/main/openapi/qdrant-collections-api-openapi.yml