Describe Index

Get detailed information about an existing index.

Authentication

Required - API key via X-API-Key header:

X-API-Key: cyborg_your_api_key_here

Any valid credential is accepted — the root key or a per-user cdbk_ token. When RBAC is not enabled (CYBORGDB_SERVICE_ROOT_KEY unset), no header is required.

Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes"
}

Show parameters

string

required

Name of the index to describe.

string

32-byte encryption key as a hex string. Required for indexes created with the SDK-supplied KEK path (provider: none). Omit for KMS-backed indexes — the service resolves the key from the index’s stored key envelope.

Response

{
  "index_name": "my_index",
  "is_trained": true,
  "dimension": 384,
  "metric": "euclidean",
  "n_lists": 1024,
  "metadata_schema": {
    "title": {"filterable": true, "pattern": true, "full_text": false}
  },
  "bm25": null
}

Show response fields

string

Name of the index.

boolean

Whether the index has been trained for optimized queries.

integer

Vector dimensionality. Returns 0 if the index was created without an explicit dimension and the first upsert has not yet happened (auto-detect pending).

string

Distance metric (euclidean, squared_euclidean, or cosine).

integer

Number of inverted lists in the IVF index. Returns 1 for untrained indexes; populated with the trained cluster count after train().

object

Per-field metadata indexing policy recorded at create time, keyed by field name (each entry has filterable, pattern, and full_text booleans). Empty object when the index uses the default index-everything posture.

object | null

BM25 scoring config when the index has at least one full_text field; null otherwise. Contains k1 and b (the tuning parameters supplied at create time, or their defaults) and analyzer_version, which identifies the tokenizer/stemmer pipeline the corpus was indexed with.

The response has no index_type or nested index_config field. There is a single index type, and its parameters are returned as top-level fields.

Exceptions

401 Unauthorized

Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model

404 Not Found

Index not found

422 Unprocessable Entity

Invalid request parameters

500 Internal Server Error

Internal server error

Example Usage

curl -X POST "http://localhost:8000/v1/indexes/describe" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here"
     }'

KMS-backed index (no key required):

curl -X POST "http://localhost:8000/v1/indexes/describe" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "kms_index"
     }'

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

Authentication

Request Body

Response

Exceptions

Example Usage

​Authentication

​Request Body

​Response

​Exceptions

​Example Usage

Authentication

Request Body

Response

Exceptions

Example Usage