> ## 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

All endpoints (except `/v1/health`) require an API key header when the service runs with `REQUIRE_API_KEY=true` (the default):

```http theme={null}
X-API-Key: cyborg_your_api_key_here
```

You can get an API key in three ways, listed from quickest to most production-ready:

| Source                                                                            | Tier     | Use case                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cyborgdb.get_demo_api_key()` / `getDemoApiKey()` / `cyborgdb.GetDemoAPIKey(...)` | **Free** | Quick evaluation — generates a real key without dashboard signup, time-limited.                                                                                                                            |
| Unset `CYBORGDB_API_KEY` on the service                                           | **Free** | Self-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 Dashboard](https://cyborgdb.co)                 | **Paid** | Production. 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](../../intro/get-api-key) guide.

## 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 (anything under `/v1/indexes/{index_name}/…` and `/v1/indexes/{upsert,query,query-binary,train,delete,…}`):

| 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 KEK itself and rejects user-supplied keys with: *"index is KMS-backed; do not supply index\_key. 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 (*"Invalid encryption key for index"*). Inspect the `detail` field to disambiguate.                                             |
| `403 Forbidden`    | RBAC routes (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>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.</Note>

## Interactive Documentation

Explore the complete API at: [http://localhost:8000/docs](http://localhost:8000/docs) after starting the service.