Retrieve the nearest neighbors for a given query vector.
Authentication Required - API key via X-API-Key header:
X-API-Key : cyborg_your_api_key_here You can get an API key from the CyborgDB Admin Dashboard . For more info, follow this guide .
Request Body Single Query Request { "index_name" : "my_index" , "index_key" : "64_character_hex_string_representing_32_bytes" , "query_vectors" : [ 0.1 , 0.2 , 0.3 , 0.4 ], "top_k" : 10 , "n_probes" : 1 , "greedy" : false , "filters" : { "category" : "greeting" }, "include" : [ "distance" , "metadata" ] } Batch Query Request { "index_name" : "my_index" , "index_key" : "64_character_hex_string_representing_32_bytes" , "query_vectors" : [ [ 0.1 , 0.2 , 0.3 , 0.4 ], [ 0.5 , 0.6 , 0.7 , 0.8 ] ], "top_k" : 10 , "n_probes" : 1 , "greedy" : false , "filters" : { "category" : "greeting" }, "include" : [ "distance" , "metadata" ] } Semantic Search Request (with embedding model) { "index_name" : "semantic_index" , "index_key" : "64_character_hex_string_representing_32_bytes" , "query_contents" : "Find documents about machine learning" , "top_k" : 10 , "filters" : { "type" : "research" }, "include" : [ "distance" , "metadata" ] } 32-byte encryption key as hex string
query_vectors
array[number] | array[array[number]]
Query vector(s) for similarity search:
Single query: [0.1, 0.2, 0.3, ...] (1D array)
Batch query: [[0.1, 0.2, ...], [0.4, 0.5, ...]] (2D array)
Required unless query_contents is provided
Text content for semantic search (requires index with embedding_model).
Alternative to query_vectors for automatic embedding generation
Number of nearest neighbors to return
Number of index lists to probe. When set to 0 or omitted, automatically determines optimal value based on index size and query requirements
Use greedy search for higher recall
MongoDB-style metadata filters
include
array[string]
default: ["distance","metadata"]
Fields to include in response: Include distance/similarity score to query vector
Include item metadata key-value pairs
Response Single Query Response When query_vectors is a 1D array or query_contents is used:
{ "results" : [ { "id" : "item_1" , "distance" : 0.123 , "metadata" : { "category" : "greeting" , "language" : "en" } }, { "id" : "item_3" , "distance" : 0.245 , "metadata" : { "category" : "greeting" , "language" : "es" } } ] } Batch Query Response When query_vectors is a 2D array (array of arrays):
{ "results" : [ [ { "id" : "item_1" , "distance" : 0.123 , "metadata" : { "category" : "greeting" }}, { "id" : "item_2" , "distance" : 0.245 , "metadata" : { "category" : "farewell" }} ], [ { "id" : "item_3" , "distance" : 0.156 , "metadata" : { "category" : "question" }}, { "id" : "item_4" , "distance" : 0.298 , "metadata" : { "category" : "answer" }} ] ] } The response format automatically matches the request format:
Single query → flat array of results
Batch query → nested array with results for each query
Use MongoDB-style query operators:
{ "filters" : { "$and" : [ { "category" : "greeting" }, { "confidence" : { "$gte" : 0.9 }} ] } } Supported operators: $and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $ninExceptions
401: Authentication failed (invalid API key)404: Index not found422: Invalid request parameters or vector dimensions500: Internal server error
Example Usage Basic Query: curl -X POST "http://localhost:8000/v1/vectors/query" \ -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", "query_vectors": [0.1, 0.2, 0.3, 0.4], "top_k": 5 }' With Filters: curl -X POST "http://localhost:8000/v1/vectors/query" \ -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", "query_vectors": [0.1, 0.2, 0.3, 0.4], "top_k": 10, "filters": { "$and": [ {"category": "document"}, {"priority": {"$gte": 3}} ] }, "include": ["distance", "metadata"] }' Semantic Search: # For indexes with embedding_model curl -X POST "http://localhost:8000/v1/vectors/query" \ -H "X-API-Key: cyborg_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "index_name": "semantic_index", "index_key": "your_64_character_hex_key_here", "query_contents": "Find documents about machine learning", "top_k": 10, "filters": {"type": "research"} }' Batch Query: curl -X POST "http://localhost:8000/v1/vectors/query" \ -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", "query_vectors": [ [0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.7, 0.8], [0.9, 0.1, 0.2, 0.3] ], "top_k": 5, "include": ["distance"] }' High Recall Query: curl -X POST "http://localhost:8000/v1/vectors/query" \ -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", "query_vectors": [0.1, 0.2, 0.3, 0.4], "top_k": 20, "n_probes": 10, "greedy": true }' If embedding_model is configured for the index, you can use either query_vectors for direct vector search or query_contents for text-based semantic search.
Higher n_probes values and greedy=true increase recall but may reduce query performance. Start with default values and adjust based on your recall requirements.
