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.

Content-Type: application/json
api-key: my-stable-namespace-key
X-Tenant-Id: optional-workspace

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.
GET /collections/{collection}: return status, point count, and vector configuration.
DELETE /collections/{collection}: delete a collection and associated points for the namespace.
PUT /collections/{collection}/index: acknowledge Qdrant payload-index compatibility calls without building a separate index.

Point endpoints

POST /collections/{collection}/points: retrieve points by ids.
PUT /collections/{collection}/points: upsert points.
POST /collections/{collection}/points/upsert: upsert points with POST.
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.

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 http://ydb-qdrant.tech:8080/collections/__missing_probe \
  -H 'api-key: demo-key'
curl -i -X POST http://ydb-qdrant.tech:8080/collections/__bad_json/points/upsert \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  --data '{bad json'
curl -i https://ydb-qdrant.tech/api/__unknown_probe
curl -i https://ydb-qdrant.tech/v1/__unknown_probe

Missing collections return COLLECTION_NOT_FOUND.
Invalid JSON returns VALIDATION_ERROR.
Unknown API-like HTTPS routes return NOT_FOUND JSON after the production proxy forwards them to the backend.

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' \
  -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}'