REST API

YDB-Qdrant REST API reference

YDB-Qdrant implements a focused Qdrant-compatible REST subset for collection metadata, point storage, exact top-k vector search, query compatibility, and point deletion.

OpenAPI JSON Auth docs

Base URLs and headers

Use https://ydb-qdrant.tech for public HTTPS API routes such as /health and /collections/..., http://ydb-qdrant.tech:8080 for the public demo Qdrant base URL, or http://localhost:8080 for a self-hosted server. Use the public HTTP demo endpoint only with non-sensitive demo credentials.

Content-Type: application/json
api-key: my-stable-namespace-key
X-Tenant-Id: optional-workspace
YDB-Qdrant-API-Version: 2026-05-28
Idempotency-Key: stable-mutation-key

YDB-Qdrant-API-Version is optional. Send 2026-05-28 when an agent or generated client needs to pin the documented REST contract.
Use Idempotency-Key when an agent or client may retry create, delete, index, upsert, or point-delete mutation requests.

API versioning and deprecation policy

YDB-Qdrant uses header-based API versioning instead of a /v1 URL prefix. The current documented value is 2026-05-28. Backward-incompatible public REST changes will be documented in OpenAPI and docs with at least 90 days of notice when the hosted API is affected.

Header: YDB-Qdrant-API-Version: 2026-05-28
OpenAPI lifecycle metadata: x-api-lifecycle
Do not probe /v1 routes for version discovery; they are not published as the current contract.

Service endpoints

GET /: returns service title and version on self-hosted servers. The public HTTPS root serves the static site.
GET /health: returns {"status":"ok"} when the app and YDB probe are ready.

Collection endpoints

PUT /collections/{collection}: create or confirm a collection with vectors.size, vectors.distance, and optional vectors.data_type. Supports Idempotency-Key.
GET /collections/{collection}: return status, point count, and vector configuration.
DELETE /collections/{collection}: delete a collection and associated points for the namespace. Supports Idempotency-Key.
PUT /collections/{collection}/index: acknowledge Qdrant payload-index compatibility calls without building a separate index. Supports Idempotency-Key.

Point endpoints

POST /collections/{collection}/points: retrieve points by ids.
PUT /collections/{collection}/points: upsert points. Supports Idempotency-Key.
POST /collections/{collection}/points/upsert: upsert points with POST. Supports Idempotency-Key.
POST /collections/{collection}/points/search: exact top-k vector search.
POST /collections/{collection}/points/query: query compatibility endpoint that accepts loose nested vector shapes.
POST /collections/{collection}/points/delete: delete by ids, empty filter, or supported pathSegments.N filters. Supports Idempotency-Key.

JSON error responses

{
  "status": "error",
  "error": "collection not found",
  "code": "COLLECTION_NOT_FOUND",
  "message": "collection not found",
  "resolution": "Create the collection first, or check the collection name, api-key, and X-Tenant-Id namespace.",
  "request_id": "req-123",
  "details": {
    "collection": "documents"
  }
}

Every API error response is application/json rather than an HTML error page.
The error field remains a string for Qdrant-compatible clients.
Agents can use code, message, resolution, request_id, and optional details for recovery and support workflows.

Error probes for agents

curl -i https://ydb-qdrant.tech/collections/__missing_probe \
  -H 'api-key: demo-key'

curl -i -X POST https://ydb-qdrant.tech/collections/__bad_json/points/upsert \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  --data '{bad json'

Missing collections return COLLECTION_NOT_FOUND.
Invalid JSON returns VALIDATION_ERROR.
Use the documented OpenAPI paths for agent probes.

Example

curl -X PUT http://localhost:8080/collections/documents \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -d '{"vectors":{"size":3,"distance":"Cosine","data_type":"float"}}'

curl -X POST http://localhost:8080/collections/documents/points/upsert \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -H 'Idempotency-Key: upsert-doc-1' \
  -d '{"points":[{"id":"doc-1","vector":[0.1,0.2,0.3],"payload":{"title":"Doc 1"}}]}'

curl -X POST http://localhost:8080/collections/documents/points/search \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -d '{"vector":[0.1,0.2,0.3],"top":10,"with_payload":true}'