openapi: 3.0.1
info:
title: Qdrant Aliases Snapshots 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: Snapshots
description: Storage and collections snapshots.
paths:
/collections/{collection_name}/snapshots/upload:
post:
tags:
- Snapshots
summary: Recover from an uploaded snapshot
description: Recover local collection data from an uploaded snapshot. This will overwrite any data, stored on this node, for the collection. If collection does not exist - it will be created.
operationId: recover_from_uploaded_snapshot
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. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
- name: priority
in: query
description: Defines source of truth for snapshot recovery
required: false
schema:
$ref: '#/components/schemas/SnapshotPriority'
- name: checksum
in: query
description: Optional SHA256 checksum to verify snapshot integrity before recovery.
required: false
schema:
type: string
requestBody:
description: Snapshot to recover from
content:
multipart/form-data:
schema:
type: object
properties:
snapshot:
type: string
format: binary
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/collections/{collection_name}/snapshots/recover:
put:
tags:
- Snapshots
summary: Recover from a snapshot
description: Recover local collection data from a snapshot. This will overwrite any data, stored on this node, for the collection. If collection does not exist - it will be created.
operationId: recover_from_snapshot
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. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
requestBody:
description: Snapshot to recover from
content:
application/json:
schema:
$ref: '#/components/schemas/SnapshotRecover'
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/collections/{collection_name}/snapshots:
get:
tags:
- Snapshots
summary: List collection snapshots
description: Get list of snapshots for a collection
operationId: list_snapshots
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:
type: array
items:
$ref: '#/components/schemas/SnapshotDescription'
post:
tags:
- Snapshots
summary: Create collection snapshot
description: Create new snapshot for a collection
operationId: create_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection for which to create a snapshot
required: true
schema:
type: string
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/SnapshotDescription'
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/collections/{collection_name}/snapshots/{snapshot_name}:
delete:
tags:
- Snapshots
summary: Delete collection snapshot
description: Delete snapshot for a collection
operationId: delete_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection for which to delete a snapshot
required: true
schema:
type: string
- name: snapshot_name
in: path
description: Name of the snapshot to delete
required: true
schema:
type: string
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
get:
tags:
- Snapshots
summary: Download collection snapshot
description: Download specified snapshot from a collection as a file
operationId: get_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: snapshot_name
in: path
description: Name of the snapshot to download
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: Snapshot file
content:
application/octet-stream:
schema:
type: string
format: binary
/snapshots:
get:
tags:
- Snapshots
summary: List of storage snapshots
description: Get list of snapshots of the whole storage
operationId: list_full_snapshots
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/SnapshotDescription'
post:
tags:
- Snapshots
summary: Create storage snapshot
description: Create new snapshot of the whole storage
operationId: create_full_snapshot
parameters:
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/SnapshotDescription'
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/snapshots/{snapshot_name}:
delete:
tags:
- Snapshots
summary: Delete storage snapshot
description: Delete snapshot of the whole storage
operationId: delete_full_snapshot
parameters:
- name: snapshot_name
in: path
description: Name of the full snapshot to delete
required: true
schema:
type: string
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
get:
tags:
- Snapshots
summary: Download storage snapshot
description: Download specified snapshot of the whole storage as a file
operationId: get_full_snapshot
parameters:
- name: snapshot_name
in: path
description: Name of the snapshot to download
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: Snapshot file
content:
application/octet-stream:
schema:
type: string
format: binary
/collections/{collection_name}/shards/{shard_id}/snapshot:
get:
tags:
- Snapshots
summary: Download shard snapshot
description: Stream the current state of a shard as a snapshot file
operationId: stream_shard_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: shard_id
in: path
description: Id of the shard
required: true
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: Snapshot file
content:
application/octet-stream:
schema:
type: string
format: binary
/collections/{collection_name}/shards/{shard_id}/snapshots/upload:
post:
tags:
- Snapshots
summary: Recover shard from an uploaded snapshot
description: Recover shard of a local collection from an uploaded snapshot. This will overwrite any data, stored on this node, for the collection shard.
operationId: recover_shard_from_uploaded_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: shard_id
in: path
description: Id of the shard to recover
required: true
schema:
type: integer
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
- name: priority
in: query
description: Defines source of truth for snapshot recovery
required: false
schema:
$ref: '#/components/schemas/SnapshotPriority'
- name: checksum
in: query
description: Optional SHA256 checksum to verify snapshot integrity before recovery.
required: false
schema:
type: string
requestBody:
description: Snapshot to recover from
content:
multipart/form-data:
schema:
type: object
properties:
snapshot:
type: string
format: binary
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/collections/{collection_name}/shards/{shard_id}/snapshots/recover:
put:
tags:
- Snapshots
summary: Recover from a snapshot
description: Recover shard of a local collection data from a snapshot. This will overwrite any data, stored in this shard, for the collection.
operationId: recover_shard_from_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: shard_id
in: path
description: Id of the shard to recover
required: true
schema:
type: integer
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
requestBody:
description: Snapshot to recover from
content:
application/json:
schema:
$ref: '#/components/schemas/ShardSnapshotRecover'
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
format: float
description: Time spent to process this request
status:
type: string
/collections/{collection_name}/shards/{shard_id}/snapshots:
get:
tags:
- Snapshots
summary: List shards snapshots for a collection
description: Get list of snapshots for a shard of a collection
operationId: list_shard_snapshots
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: shard_id
in: path
description: Id of the shard
required: true
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: array
items:
$ref: '#/components/schemas/SnapshotDescription'
post:
tags:
- Snapshots
summary: Create shard snapshot
description: Create new snapshot of a shard for a collection
operationId: create_shard_snapshot
parameters:
- name: collection_name
in: path
description: Name of the collection for which to create a snapshot
required: true
schema:
type: string
- name: shard_id
in: path
description: Id of the shard
required: true
schema:
type: integer
- name: wait
in: query
description: If true, wait for changes to actually happen. If false - let changes happen in background. Default is true.
required: false
schema:
type: boolean
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:
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/SnapshotDescription'
'202':
description: operation is accepted
content:
application/json:
schema:
type: object
properties:
time:
type: number
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qdrant/refs/heads/main/openapi/qdrant-snapshots-api-openapi.yml