Skip to main content
The CyborgDB REST API provides HTTP/HTTPS endpoints for all encrypted vector database operations using standard RESTful principles and JSON responses.

​
Base URL

Development: http://localhost:8000/v1
Production: https://your-domain.com:8000/v1

​
Authentication

All endpoints (except /v1/health) require an API key header when the service runs with REQUIRE_API_KEY=true (the default): 
X-API-Key: cyborg_your_api_key_here
You can get an API key in three ways, listed from quickest to most production-ready:
SourceTierUse case
cyborgdb.get_demo_api_key() / getDemoApiKey() / cyborgdb.GetDemoAPIKey(...)FreeQuick evaluation — generates a real key without dashboard signup, time-limited.
Unset CYBORGDB_API_KEY on the serviceFreeSelf-hosted evaluation. Service runs with the core library’s 1M-item-per-index cap; the same empty value is treated as the bearer credential, so you also need REQUIRE_API_KEY=false to skip the header.
Paid key from the CyborgDB Admin DashboardPaidProduction. Unlimited items, full feature set. Set as CYBORGDB_API_KEY on the service and pass the same value as X-API-Key.
For full details, follow the Get an API Key guide.

​
Response Format

Success: 
{
  "status": "success",
  "message": "Operation completed successfully"
}
Error: 
{
  "status_code": 400,
  "detail": "Error description"
}

​
Error model: API keys, index keys, and KMS

A small amount of nuance applies to error codes on index-scoped routes (anything under /v1/indexes/{index_name}/… and /v1/indexes/{upsert,query,query-binary,train,delete,…}):
StatusMeaning
400 Bad RequestThe request is malformed for this index’s key path. The most common case is supplying index_key (header or body) for a KMS-backed index — the service resolves the KEK itself and rejects user-supplied keys with: “index is KMS-backed; do not supply index_key. Omit index_key from the request.”
401 UnauthorizedEither (a) the X-API-Key header is missing/invalid, or (b) for SDK-supplied indexes, the index_key was supplied but does not match the key the index was created with (“Invalid encryption key for index”). Inspect the detail field to disambiguate.
403 ForbiddenRBAC routes (user create/list/delete) called without the root API key, or when RBAC is not enabled on the service.
404 Not FoundThe named index does not exist.
Wrong-index_key returns 401 in v0.17 (previously some paths returned 500). KMS-backed indexes that receive an unexpected index_key return 400 rather than silently ignoring it — this surfaces SDK-versus-KMS confusion early.

​
Interactive Documentation

Explore the complete API at: http://localhost:8000/docs after starting the service.