openapi: 3.0.1
info:
title: Qdrant Aliases Service 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: Service
description: Qdrant service utilities.
paths:
/:
get:
summary: Returns information about the running Qdrant instance
description: Returns information about the running Qdrant instance like version and commit id
operationId: root
tags:
- Service
responses:
'200':
description: Qdrant server version information
content:
application/json:
schema:
$ref: '#/components/schemas/VersionInfo'
4XX:
description: error
/telemetry:
get:
summary: Collect telemetry data
description: Collect telemetry data including app info, system info, collections info, cluster info, configs and statistics
operationId: telemetry
tags:
- Service
parameters:
- name: anonymize
in: query
description: If true, anonymize result
required: false
schema:
type: boolean
- name: details_level
in: query
description: Level of details in telemetry data. Minimal level is 0, maximal is infinity
required: false
schema:
type: integer
minimum: 0
- name: per_collection
in: query
description: If true, include per-collection request statistics in the response
required: false
schema:
type: boolean
- name: timeout
in: query
description: Timeout for this request
required: false
schema:
type: integer
minimum: 1
default: 60
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/TelemetryData'
/metrics:
get:
summary: Collect Prometheus metrics data
description: Collect metrics data including app info, collections info, cluster info and statistics
operationId: metrics
tags:
- Service
parameters:
- name: anonymize
in: query
description: If true, anonymize result
required: false
schema:
type: boolean
- name: per_collection
in: query
description: If true, include per-collection request metrics with a collection label instead of global request metrics
required: false
schema:
type: boolean
- name: timeout
in: query
description: Timeout for this request
required: false
schema:
type: integer
minimum: 1
default: 60
responses:
'200':
description: Metrics data in Prometheus format
content:
text/plain:
schema:
type: string
example: '# HELP app_info information about qdrant server
# TYPE app_info gauge
app_info{name="qdrant",version="0.11.1"} 1
# HELP cluster_enabled is cluster support enabled
# TYPE cluster_enabled gauge
cluster_enabled 0
# HELP collections_total number of collections
# TYPE collections_total gauge
collections_total 1
'
4XX:
description: error
/healthz:
get:
summary: Kubernetes healthz endpoint
description: An endpoint for health checking used in Kubernetes.
operationId: healthz
tags:
- Service
responses:
'200':
description: Healthz response
content:
text/plain:
schema:
type: string
example: healthz check passed
4XX:
description: error
/livez:
get:
summary: Kubernetes livez endpoint
description: An endpoint for health checking used in Kubernetes.
operationId: livez
tags:
- Service
responses:
'200':
description: Healthz response
content:
text/plain:
schema:
type: string
example: healthz check passed
4XX:
description: error
/readyz:
get:
summary: Kubernetes readyz endpoint
description: An endpoint for health checking used in Kubernetes.
operationId: readyz
tags:
- Service
responses:
'200':
description: Healthz response
content:
text/plain:
schema:
type: string
example: healthz check passed
4XX:
description: error
components:
schemas:
CollectionTelemetryEnum:
anyOf:
- $ref: '#/components/schemas/CollectionTelemetry'
- $ref: '#/components/schemas/CollectionsAggregatedTelemetry'
BinaryQuantization:
type: object
required:
- binary
properties:
binary:
$ref: '#/components/schemas/BinaryQuantizationConfig'
OptimizerTelemetry:
type: object
required:
- optimizations
- status
properties:
status:
$ref: '#/components/schemas/OptimizersStatus'
optimizations:
$ref: '#/components/schemas/OperationDurationStatistics'
log:
type: array
items:
$ref: '#/components/schemas/TrackerTelemetry'
nullable: true
ShardUpdateQueueInfo:
type: object
required:
- length
properties:
length:
description: Number of elements in the queue
type: integer
format: uint
minimum: 0
op_num:
description: last operation number processed
type: integer
format: uint
minimum: 0
nullable: true
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
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
ReshardingInfo:
type: object
required:
- direction
- peer_id
- shard_id
properties:
direction:
$ref: '#/components/schemas/ReshardingDirection'
shard_id:
type: integer
format: uint32
minimum: 0
peer_id:
type: integer
format: uint64
minimum: 0
shard_key:
anyOf:
- $ref: '#/components/schemas/ShardKey'
- nullable: true
BinaryQuantizationEncoding:
type: string
enum:
- one_bit
- two_bits
- one_and_half_bits
ShardCleanStatusFailedTelemetry:
type: object
required:
- reason
properties:
reason:
type: string
TrackerTelemetry:
description: Tracker object used in telemetry
type: object
required:
- name
- segment_ids
- segment_uuids
- start_at
- status
- uuid
properties:
name:
description: Name of the optimizer
type: string
uuid:
description: UUID of the upcoming segment being created by the optimizer
type: string
format: uuid
segment_ids:
description: Internal segment IDs being optimized. These are local and in-memory, meaning that they can refer to different segments after a service restart.
type: array
items:
type: integer
format: uint
minimum: 0
segment_uuids:
description: Segment UUIDs being optimized. Refers to same segments as in `segment_ids`, but trackable across restarts, and reflect their directory name.
type: array
items:
type: string
format: uuid
status:
$ref: '#/components/schemas/TrackerStatus'
start_at:
description: Start time of the optimizer
type: string
format: date-time
end_at:
description: End time of the optimizer
type: string
format: date-time
nullable: true
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
HnswGlobalConfig:
type: object
properties:
healing_threshold:
description: Enable HNSW healing if the ratio of missing points is no more than this value. To disable healing completely, set this value to `0.0`.
default: 0.3
type: number
format: double
maximum: 1
minimum: 0
Payload:
type: object
additionalProperties: true
example:
city: London
color: green
InferenceUsage:
type: object
required:
- models
properties:
models:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelUsage'
VectorDataConfig:
description: Config of single vector data storage
type: object
required:
- distance
- index
- size
- storage_type
properties:
size:
description: Size/dimensionality of the vectors used
type: integer
format: uint
minimum: 0
distance:
$ref: '#/components/schemas/Distance'
storage_type:
$ref: '#/components/schemas/VectorStorageType'
index:
$ref: '#/components/schemas/Indexes'
quantization_config:
description: Vector specific quantization config that overrides collection config
anyOf:
- $ref: '#/components/schemas/QuantizationConfig'
- nullable: true
multivector_config:
description: Vector specific configuration to enable multiple vectors per point
anyOf:
- $ref: '#/components/schemas/MultiVectorConfig'
- nullable: true
datatype:
description: Vector specific configuration to set specific storage element type
anyOf:
- $ref: '#/components/schemas/VectorStorageDatatype'
- nullable: true
ShardTransferInfo:
type: object
required:
- from
- shard_id
- sync
- to
properties:
shard_id:
type: integer
format: uint32
minimum: 0
to_shard_id:
description: 'Target shard ID if different than source shard ID
Used exclusively with `ReshardingStreamRecords` transfer method.'
type: integer
format: uint32
minimum: 0
nullable: true
from:
description: Source peer id
type: integer
format: uint64
minimum: 0
to:
description: Destination peer id
type: integer
format: uint64
minimum: 0
sync:
description: If `true` transfer is a synchronization of a replicas If `false` transfer is a moving of a shard from one peer to another
type: boolean
method:
anyOf:
- $ref: '#/components/schemas/ShardTransferMethod'
- nullable: true
comment:
description: A human-readable report of the transfer progress. Available only on the source peer.
type: string
nullable: true
ShardKey:
anyOf:
- type: string
example: region_1
- type: integer
format: uint64
minimum: 0
example: 12
PayloadSchemaType:
description: All possible names of payload types
type: string
enum:
- keyword
- integer
- float
- geo
- text
- bool
- datetime
- uuid
FeatureFlags:
type: object
properties:
all:
description: 'Magic feature flag that enables all features.
Note that this will only be applied to all flags when passed into [`init_feature_flags`].'
default: false
type: boolean
payload_index_skip_rocksdb:
description: 'Skip usage of RocksDB in new immutable payload indices.
First implemented in Qdrant 1.13.5. Enabled by default in Qdrant 1.14.1.'
default: true
type: boolean
payload_index_skip_mutable_rocksdb:
description: 'Skip usage of RocksDB in new mutable payload indices.
First implemented in Qdrant 1.15.0. Enabled by default in Qdrant 1.16.0.'
default: true
type: boolean
payload_storage_skip_rocksdb:
description: 'Skip usage of RocksDB in new payload storages.
On-disk payload storages never use Gridstore.
First implemented in Qdrant 1.15.0. Enabled by default in Qdrant 1.16.0.'
default: true
type: boolean
incremental_hnsw_building:
description: 'Use incremental HNSW building.
Enabled by default in Qdrant 1.14.1.'
default: true
type: boolean
migrate_rocksdb_id_tracker:
description: 'Migrate RocksDB based ID trackers into file based ID tracker on start.
Enabled by default in Qdrant 1.15.0.'
default: true
type: boolean
migrate_rocksdb_vector_storage:
description: 'Migrate RocksDB based vector storages into new format on start.
Enabled by default in Qdrant 1.16.1.'
default: true
type: boolean
migrate_rocksdb_payload_storage:
description: 'Migrate RocksDB based payload storages into new format on start.
Enabled by default in Qdrant 1.16.1.'
default: true
type: boolean
migrate_rocksdb_payload_indices:
description: 'Migrate RocksDB based payload indices into new format on start.
Rebuilds a new payload index from scratch.
Enabled by default in Qdrant 1.16.1.'
default: true
type: boolean
appendable_quantization:
description: 'Use appendable quantization in appendable plain segments.
Enabled by default in Qdrant 1.16.0.'
default: true
type: boolean
single_file_mmap_vector_storage:
description: 'Use single-file mmap in-ram vector storage (InRamMmap)
Enabled by default in Qdrant 1.17.1+'
default: false
type: boolean
QuantizationConfig:
anyOf:
- $ref: '#/components/schemas/ScalarQuantization'
- $ref: '#/components/schemas/ProductQuantization'
- $ref: '#/components/schemas/BinaryQuantization'
ReshardingDirection:
description: 'Resharding direction, scale up or down in number of shards
- `up` - Scale up, add a new shard
- `down` - Scale down, remove a shard'
type: string
enum:
- up
- down
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
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
ConsensusThreadStatus:
description: Information about current consensus thread status
oneOf:
- type: object
required:
- consensus_thread_status
- last_update
properties:
consensus_thread_status:
type: string
enum:
- working
last_update:
type: string
format: date-time
- type: object
required:
- consensus_thread_status
properties:
consensus_thread_status:
type: string
enum:
- stopped
- type: object
required:
- consensus_thread_status
- err
properties:
consensus_thread_status:
type: string
enum:
- stopped_with_err
err:
type: string
ShardCleanStatusTelemetry:
oneOf:
- type: string
enum:
- started
- done
- cancelled
- type: object
required:
- progress
properties:
progress:
$ref: '#/components/schemas/ShardCleanStatusProgressTelemetry'
additionalProperties: false
- type: object
required:
- failed
properties:
failed:
$ref: '#/components/schemas/ShardCleanStatusFailedTelemetry'
additionalProperties: false
StrictModeMultivectorConfigOutput:
type: object
additionalProperties:
$ref: '#/components/schemas/StrictModeMultivectorOutput'
ScalarQuantization:
type: object
required:
- scalar
properties:
scalar:
$ref: '#/components/schemas/ScalarQuantizationConfig'
WebApiTelemetry:
type: object
required:
- responses
properties:
responses:
type: object
additionalProperties:
type: object
additionalProperties:
$ref: '#/components/schemas/OperationDurationStatistics'
per_collection_responses:
type: object
additionalProperties:
type: object
additionalProperties:
type: object
additionalProperties:
$ref: '#/components/schemas/OperationDurationStatistics'
FloatIndexType:
type: string
enum:
- float
ProductQuantizationConfig:
type: object
required:
- compression
properties:
compression:
$ref: '#/components/schemas/CompressionRatio'
always_ram:
type: boolean
nullable: true
PeerInfo:
description: Information of a peer in the cluster
type: object
required:
- uri
properties:
uri:
type: string
HardwareTelemetry:
type: object
required:
- collection_data
properties:
collection_data:
type: object
additionalProperties:
$ref: '#/components/schemas/HardwareUsage'
OperationDurationStatistics:
type: object
required:
- count
properties:
count:
type: integer
format: uint
minimum: 0
fail_count:
type: integer
format: uint
minimum: 0
nullable: true
avg_duration_micros:
description: The average time taken by 128 latest operations, calculated as a weighted mean.
type: number
format: float
nullable: true
min_duration_micros:
description: The minimum duration of the operations across all the measurements.
type: number
format: float
nullable: t
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qdrant/refs/heads/main/openapi/qdrant-service-api-openapi.yml