> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CyborgDB REST API Reference

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

Authentication is controlled by the service's `CYBORGDB_SERVICE_ROOT_KEY`. When it is **unset** (the default), authentication is disabled — every endpoint is open and no header is required. When it is **set**, all endpoints except `/v1/health` require a credential in the `X-API-Key` header:

```http theme={null}
X-API-Key: your-root-key-or-cdbk-token
```

The accepted credential is either the root key itself or a per-user `cdbk_` token minted under it (see [Managing Keys](../guides/advanced/managing-keys)).

<Note>
  This `X-API-Key` credential is **not** the same as `CYBORGDB_API_KEY`. `CYBORGDB_API_KEY` is the core *license* key — it sets the usage tier (unset → free tier with a 1M-item-per-index cap; a paid key from the [CyborgDB Admin Dashboard](https://cyborgdb.co/new) → unlimited) and is never sent by clients. Service request authentication is gated only by `CYBORGDB_SERVICE_ROOT_KEY`.
</Note>

## Response Format

**Success:**

```json theme={null}
{
  "status": "success",
  "message": "Operation completed successfully"
}
```

**Error:**

```json theme={null}
{
  "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 — the data-plane routes under `/v1/vectors/…` (`upsert`, `upsert_binary`, `query`, `query_binary`, `query_metadata`, `get`, `delete`, `list_ids`, `num_vectors`) and the index-lifecycle routes under `/v1/indexes/…` (`create`, `train`, `delete`, `training-status`, …):

| Status | Meaning |
| - | - |
| `400 Bad Request` | The 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 key itself using its KMS configuration, so the error `detail` says the index is KMS-backed and asks you to omit `index_key` from the request. |
| `401 Unauthorized` | Either (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 (*"Wrong encryption key for index '\<name>'"*). Inspect the `detail` field to disambiguate. |
| `403 Forbidden` | An admin-gated route (`/v1/indexes/list`, `create`, `delete`, `train`, `training-status`) called with a non-root (`cdbk_`) API key, or an RBAC route (user create/list/delete) called without the root API key or when RBAC is not enabled on the service. |
| `404 Not Found` | The named index does not exist. |

<Note>A wrong `index_key` returns **401**. KMS-backed indexes that receive an unexpected `index_key` return **400** rather than silently ignoring it — this surfaces SDK-versus-KMS confusion early.</Note>

## Interactive Documentation

Explore the complete API at: [http://localhost:8000/v1/docs](http://localhost:8000/v1/docs) after starting the service. ReDoc is served at `/v1/redoc` and the OpenAPI spec at `/v1/openapi.json`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.