API Overview

VortexDB provides two complementary APIs for different use cases:

Available APIs

gRPC API

High-performance Protocol Buffer interface for production workloads

HTTP API

RESTful JSON interface for quick testing and prototyping

Comparison

Feature	gRPC	HTTP
Protocol	HTTP/2 + Protobuf	HTTP/1.1 + JSON
Default Port	50051	3000
Authentication	API key required	API key required
Performance	Higher throughput	Lower latency for simple requests
Client Libraries	Auto-generated	Any HTTP client
Best For	Production, SDKs	Debugging, curl

Authentication

gRPC

The gRPC API requires authentication via the authorization header:

# Using grpcurl
grpcurl -plaintext \
  -H "authorization: your-api-key" \
  localhost:50051 vectordb.VectorDB/GetPoint

# Python SDK
db = VortexDB(
    grpc_url="localhost:50051",
    api_key="your-api-key"
)

HTTP

The HTTP API requires an api-key header on every request under /points. / and /health remain open for health checks.

curl -X POST "http://localhost:3000/points/search" \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"vector": [0.1, 0.2, 0.3], "similarity": "Cosine", "limit": 5}'

Keys come from the same VORTEXDB_KEYS_FILE used by gRPC (see gRPC API), but the HTTP API additionally enforces each key’s role: readonly keys can fetch and search points; readwrite keys can also insert, batch-insert, and delete. A readonly key used against a write route gets 403 Forbidden; a missing or unrecognized key gets 401 Unauthorized.

Common Operations

Both APIs support the same core operations:

Operation	gRPC Method	HTTP Endpoint
Insert vector	`InsertVector`	`POST /points`
Batch insert	`InsertVectorsBatch`	`POST /points/batch`
Get point	`GetPoint`	`GET /points/:id`
Delete point	`DeletePoint`	`DELETE /points/:id`
Search vectors	`SearchPoints`	`POST /points/search`
Batch search	`SearchPointsBatch`	`POST /points/search/batch`
Health check	-	`GET /health`

Error Handling

gRPC Error Codes

Code	Name	Description
`0`	OK	Success
`3`	INVALID_ARGUMENT	Invalid request parameters
`5`	NOT_FOUND	Point not found
`13`	INTERNAL	Server error
`16`	UNAUTHENTICATED	Invalid or missing API key

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created (for insert)
`204`	No Content (for delete)
`400`	Bad Request
`404`	Not Found
`500`	Internal Server Error

Data Types

Vector

A dense vector of floating-point values:

gRPC (Protobuf)
HTTP (JSON)

message DenseVector {
  repeated float values = 1;
}

{
  "vector": [0.1, 0.2, 0.3, 0.4]
}

Payload

Metadata attached to vectors:

gRPC (Protobuf)
HTTP (JSON)

enum ContentType {
  Image = 0;
  Text = 1;
}

message Payload {
  ContentType content_type = 1;
  string content = 2;
}

{
  "payload": {
    "content_type": "Text",
    "content": "Hello, world!"
  }
}

Similarity Metric

Distance function for search:

Value	gRPC Enum	HTTP String
Euclidean (L2)	`0`	`"Euclidean"`
Manhattan (L1)	`1`	`"Manhattan"`
Hamming	`2`	`"Hamming"`
Cosine	`3`	`"Cosine"`

Rate Limiting

VortexDB does not implement built-in rate limiting. For production deployments, use a reverse proxy or API gateway to enforce limits.

API Reference

API Overview

API Overview

Available APIs

gRPC API

HTTP API

Comparison

Authentication

gRPC

HTTP

Common Operations

Error Handling

gRPC Error Codes

HTTP Status Codes

Data Types

Vector

Payload

Similarity Metric

Rate Limiting

Next Steps

gRPC Reference

HTTP Reference

​API Overview

​Available APIs

gRPC API

HTTP API

​Comparison

​Authentication

​gRPC

​HTTP

​Common Operations

​Error Handling

​gRPC Error Codes

​HTTP Status Codes

​Data Types

​Vector

​Payload

​Similarity Metric

​Rate Limiting

​Next Steps

gRPC Reference

HTTP Reference

API Overview

Available APIs

Comparison

Authentication

gRPC

HTTP

Common Operations

Error Handling

gRPC Error Codes

HTTP Status Codes

Data Types

Vector

Payload

Similarity Metric

Rate Limiting

Next Steps