Get Vectors

Retrieve specific vectors from the index by their IDs.

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",
  "ids": ["item_1", "item_2", "item_3"],
  "include": ["vector", "contents", "metadata"]
}

Show parameters

string

required

Name of the target index

string

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

array[string]

required

List of item IDs to retrieve

array[string]

default:["vector","contents","metadata"]

Fields to include in response:

Show include options

string

Include the stored rerank vector. Returned at the index’s configured storage_precision (float32 by default; float16 or a TurboQuant tier tq12/tq8/tq6/tq4 if set at create time).

string

Include text content associated with the vector

string

Include item metadata key-value pairs

Response

{
  "results": [
    {
      "id": "item_1",
      "vector": [0.1, 0.2, 0.3, 0.4],
      "contents": "Hello world!",
      "metadata": {"category": "greeting", "language": "en"}
    },
    {
      "id": "item_2",
      "vector": [0.5, 0.6, 0.7, 0.8],
      "contents": "Bonjour monde!",
      "metadata": {"category": "greeting", "language": "fr"}
    }
  ]
}

If an item ID doesn’t exist, it will be omitted from the results.

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

Get All Fields:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -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",
       "ids": ["item_1", "item_2", "item_3"]
     }'

Get Only Contents:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -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",
       "ids": ["doc_1", "doc_2", "doc_3"],
       "include": ["contents"]
     }'

Get Metadata Only:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -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",
       "ids": ["user_1", "user_2"],
       "include": ["metadata"]
     }'

Batch Retrieval:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -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",
       "ids": [
         "batch_1", "batch_2", "batch_3", "batch_4", "batch_5",
         "batch_6", "batch_7", "batch_8", "batch_9", "batch_10"
       ],
       "include": ["contents", "metadata"]
     }'

Example Response (Contents Only):

{
  "results": [
    {
      "id": "doc_1",
      "contents": "First document content here..."
    },
    {
      "id": "doc_2",
      "contents": "Second document content here..."
    },
    {
      "id": "doc_3",
      "contents": "Third document content here..."
    }
  ]
}

Example Response (Metadata Only):

{
  "results": [
    {
      "id": "user_1",
      "metadata": {
        "name": "Alice Smith",
        "role": "admin",
        "department": "engineering",
        "created": "2024-01-01"
      }
    },
    {
      "id": "user_2",
      "metadata": {
        "name": "Bob Johnson",
        "role": "user",
        "department": "marketing",
        "created": "2024-01-02"
      }
    }
  ]
}

Use Cases

Content retrieval: Get original text content by ID
Metadata lookup: Retrieve item metadata for display
Data validation: Verify stored data integrity
Bulk operations: Retrieve multiple items efficiently
Content management: Extract specific items for editing or processing

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

Authentication

Request Body

Response

Exceptions

Example Usage

Use Cases

​Authentication

​Request Body

​Response

​Exceptions

​Example Usage

​Use Cases

Authentication

Request Body

Response

Exceptions

Example Usage

Use Cases