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

# Describe Index

Get detailed information about an existing index.

## Authentication

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

```http theme={null}
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

```json theme={null}
{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes"
}
```

<Expandable title="parameters">
  <ParamField body="index_name" type="string" required="true">
    Name of the index to describe.
  </ParamField>

  <ParamField body="index_key" type="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.
  </ParamField>
</Expandable>

## Response

```json theme={null}
{
  "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
}
```

<Expandable title="response fields">
  <ResponseField name="index_name" type="string">
    Name of the index.
  </ResponseField>

  <ResponseField name="is_trained" type="boolean">
    Whether the index has been trained for optimized queries.
  </ResponseField>

  <ResponseField name="dimension" type="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).
  </ResponseField>

  <ResponseField name="metric" type="string">
    Distance metric (`euclidean`, `squared_euclidean`, or `cosine`).
  </ResponseField>

  <ResponseField name="n_lists" type="integer">
    Number of inverted lists in the IVF index. Returns `1` for untrained indexes; populated with the trained cluster count after `train()`.
  </ResponseField>

  <ResponseField name="metadata_schema" type="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.
  </ResponseField>

  <ResponseField name="bm25" type="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.
  </ResponseField>
</Expandable>

<Note>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.</Note>

## Exceptions

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Authentication failed (invalid API key) **or** wrong `index_key` on SDK-supplied indexes — see [error model](../introduction#error-model-api-keys-index-keys-and-kms)
  </Accordion>

  <Accordion title="404 Not Found">
    Index not found
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    Invalid request parameters
  </Accordion>

  <Accordion title="500 Internal Server Error">
    Internal server error
  </Accordion>
</AccordionGroup>

## Example Usage

```bash theme={null}
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):**

```bash theme={null}
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"
     }'
```


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