gRPC API

gRPC API Reference

VortexDB’s gRPC API provides high-performance vector operations using Protocol Buffers over HTTP/2.

Connection

Parameter	Default
Host	localhost
Port	50051
Protocol	HTTP/2 (plaintext)

# Test connection with grpcurl
grpcurl -plaintext localhost:50051 list

Authentication

All gRPC calls require the authorization header with your API key:

-H "authorization: your-api-key"

Valid keys come from the JSON file pointed to by the VORTEXDB_KEYS_FILE environment variable, shared with the HTTP server. readonly keys can call GetPoint, SearchPoints, and SearchPointsBatch; readwrite keys can additionally call InsertVector, InsertVectorsBatch, and DeletePoint. A readonly key calling a write RPC gets a PERMISSION_DENIED status.

---

Service Definition

syntax = "proto3";
package vectordb;

service VectorDB {
  rpc InsertVector(InsertVectorRequest) returns (PointID);
  rpc InsertVectorsBatch(InsertVectorsBatchRequest) returns (InsertVectorsBatchResponse);
  rpc DeletePoint(PointID) returns (google.protobuf.Empty);
  rpc GetPoint(PointID) returns (Point);
  rpc SearchPoints(SearchRequest) returns (SearchResponse);
  rpc SearchPointsBatch(SearchPointsBatchRequest) returns (SearchPointsBatchResponse);
}

---

Methods

InsertVector

Insert a vector with its associated payload.

vectorDenseVectorrequired

The vector to insert. Must match the configured DIMENSION.

payloadPayloadrequired

Metadata associated with the vector.

Request:

message InsertVectorRequest {
  DenseVector vector = 1;
  Payload payload = 2;
}

Response:

message PointID {
  UUID id = 1;
}

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{
    "vector": {"values": [0.1, 0.2, 0.3, 0.4]},
    "payload": {"content_type": 1, "content": "Hello world"}
  }' \
  localhost:50051 vectordb.VectorDB/InsertVector

Response:

{
  "id": {
    "value": "550e8400-e29b-41d4-a716-446655440000"
  }
}

---

GetPoint

Retrieve a point by its ID.

idUUIDrequired

The unique identifier of the point.

Request:

message PointID {
  UUID id = 1;
}

Response:

message Point {
  PointID id = 1;
  Payload payload = 2;
  DenseVector vector = 3;
}

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{"id": {"value": "550e8400-e29b-41d4-a716-446655440000"}}' \
  localhost:50051 vectordb.VectorDB/GetPoint

Response:

{
  "id": {
    "id": {
      "value": "550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "payload": {
    "contentType": "Text",
    "content": "Hello world"
  },
  "vector": {
    "values": [0.1, 0.2, 0.3, 0.4]
  }
}

---

DeletePoint

Delete a point by its ID.

idUUIDrequired

The unique identifier of the point to delete.

Request:

message PointID {
  UUID id = 1;
}

Response:

google.protobuf.Empty

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{"id": {"value": "550e8400-e29b-41d4-a716-446655440000"}}' \
  localhost:50051 vectordb.VectorDB/DeletePoint

Response:

{}

---

SearchPoints

Search for the k nearest neighbors to a query vector.

query_vectorDenseVectorrequired

The vector to search with. Must match the configured DIMENSION.

similaritySimilarityrequired

The distance metric to use.

limituint64required

Maximum number of results to return.

efuint64

Search breadth for HNSW. Larger values trade speed for accuracy. Defaults to the server’s HNSW_EF setting.

Request:

message SearchRequest {
  DenseVector query_vector = 1;
  Similarity similarity = 2;
  uint64 limit = 3;
  uint64 ef = 4;
}

Response:

message SearchResponse {
  repeated PointID result_point_ids = 1;
}

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{
    "query_vector": {"values": [0.1, 0.2, 0.3, 0.4]},
    "similarity": 3,
    "limit": 5,
    "ef": 200
  }' \
  localhost:50051 vectordb.VectorDB/SearchPoints

Response:

{
  "resultPointIds": [
    {"id": {"value": "550e8400-e29b-41d4-a716-446655440000"}},
    {"id": {"value": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"}}
  ]
}

---

InsertVectorsBatch

Insert multiple vectors in a single request.

Request:

message InsertVectorsBatchRequest {
  repeated InsertVectorRequest vectors = 1;
}

Response:

message InsertVectorsBatchResponse {
  repeated PointID ids = 1;
}

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{
    "vectors": [
      {"vector": {"values": [0.1, 0.2, 0.3]}, "payload": {"content_type": 1, "content": "doc one"}},
      {"vector": {"values": [0.4, 0.5, 0.6]}, "payload": {"content_type": 1, "content": "doc two"}}
    ]
  }' \
  localhost:50051 vectordb.VectorDB/InsertVectorsBatch

---

SearchPointsBatch

Search against multiple query vectors in a single request.

Request:

message SearchPointsBatchRequest {
  repeated SearchRequest queries = 1;
}

Response:

message SearchPointsBatchResponse {
  repeated SearchResponse results = 1;
}

Example:

grpcurl -plaintext \
  -H "authorization: secret" \
  -d '{
    "queries": [
      {"query_vector": {"values": [0.1, 0.2, 0.3]}, "similarity": 3, "limit": 2},
      {"query_vector": {"values": [0.4, 0.5, 0.6]}, "similarity": 0, "limit": 2}
    ]
  }' \
  localhost:50051 vectordb.VectorDB/SearchPointsBatch

---

Message Types

UUID

message UUID {
  string value = 1;  // UUID v4 string
}

DenseVector

message DenseVector {
  repeated float values = 1;  // Vector components
}

Point

message Point {
  PointID id = 1;        // Unique identifier
  Payload payload = 2;   // Associated metadata
  DenseVector vector = 3; // Vector values
}

PointID

message PointID {
  UUID id = 1;
}

Payload

message Payload {
  ContentType content_type = 1;  // Type of content
  string content = 2;            // Content string
}

---

Enums

Similarity

Distance/similarity metric for search operations.

Value	Name	Description
0	Euclidean	L2 distance (straight line)
1	Manhattan	L1 distance (city block)
2	Hamming	Count of differing elements
3	Cosine	Angular distance

ContentType

Type of payload content.

Value	Name	Description
0	Image	Image reference or data
1	Text	Text content

---

Error Codes

gRPC Code	Name	Description
0	OK	Success
3	INVALID_ARGUMENT	Invalid request (e.g., wrong dimensions)
5	NOT_FOUND	Point does not exist
13	INTERNAL	Server error
16	UNAUTHENTICATED	Invalid or missing API key

---

Client Libraries

Python

from vortexdb import VortexDB, DenseVector, Payload, Similarity

with VortexDB(grpc_url="localhost:50051", api_key="secret") as db:
    # Insert
    point_id = db.insert(
        vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
        payload=Payload.text("Hello")
    )

    # Batch insert
    ids = db.batch_insert(items=[
        (DenseVector([0.1, 0.2, 0.3]), Payload.text("doc one")),
        (DenseVector([0.4, 0.5, 0.6]), Payload.text("doc two")),
    ])

    # Search with ef parameter
    results = db.search(
        vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
        similarity=Similarity.COSINE,
        limit=5,
        ef=200,
    )

Generate Clients

Use protoc to generate clients in any language:

python -m grpc_tools.protoc \
  -I./crates/grpc/proto \
  --python_out=./client \
  --grpc_python_out=./client \
  ./crates/grpc/proto/vector-db.proto

Next Steps

HTTP API

REST API reference

Python SDK

Python client documentation