@ruvector/server

@ruvector/server

HTTP and gRPC server for the RuVector vector database, providing a full REST API with streaming support, authentication, collection management, and production-grade deployment features.

Quick Command Reference

Installation

Hub install (recommended): npx ruvector@latest includes this package. Standalone: npx @ruvector/server@latest See Installation Guide for the full ecosystem.

Core API

Programmatic Server

import { createServer } from '@ruvector/server';

const server = createServer({
  port: 8080,
  grpcPort: 50051,        // Optional gRPC
  persistPath: './data',
  authToken: process.env.RV_TOKEN,
  cors: true,
  tls: { cert: 'cert.pem', key: 'key.pem' },
});

await server.start();

Server Options:

REST API Endpoints

Collections

GET    /api/v1/collections                          # List all collections
POST   /api/v1/collections                          # Create collection
GET    /api/v1/collections/:name                    # Get collection info
DELETE /api/v1/collections/:name                    # Delete collection

Vectors

POST   /api/v1/collections/:name/vectors            # Insert vector(s)
GET    /api/v1/collections/:name/vectors/:id         # Get vector by ID
DELETE /api/v1/collections/:name/vectors/:id         # Delete vector
PUT    /api/v1/collections/:name/vectors/:id         # Update vector
POST   /api/v1/collections/:name/vectors/batch       # Batch insert

Search

POST   /api/v1/collections/:name/search             # Vector search
POST   /api/v1/collections/:name/search/batch       # Batch search

Management

GET    /api/v1/health                                # Health check
GET    /api/v1/metrics                               # Prometheus metrics
POST   /api/v1/collections/:name/index/build         # Build HNSW index
GET    /api/v1/collections/:name/index/status        # Index status

Request/Response Examples

Create Collection:

curl -X POST http://localhost:8080/api/v1/collections \
  -H "Content-Type: application/json" \
  -d '{"name":"docs","dimensions":384,"metric":"cosine"}'

Insert Vector:

curl -X POST http://localhost:8080/api/v1/collections/docs/vectors \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"id":"v1","vector":[0.1,0.2,0.3],"metadata":{"title":"Hello"}}'

Search:

curl -X POST http://localhost:8080/api/v1/collections/docs/search \
  -d '{"vector":[0.1,0.2,0.3],"topK":5,"filter":{"category":"ai"}}'

Common Patterns

Production Deployment

npx @ruvector/server@latest \
  --port 8080 \
  --persist ./vector-data \
  --auth-token $RV_AUTH_TOKEN \
  --tls --cert /etc/ssl/cert.pem --key /etc/ssl/key.pem \
  --cors

Docker Deployment

import { createServer } from '@ruvector/server';

const server = createServer({
  port: parseInt(process.env.PORT || '8080'),
  persistPath: '/data/vectors',
  authToken: process.env.AUTH_TOKEN,
  cors: true,
});
await server.start();

Multi-Collection Setup

# Create multiple collections for different embedding models
curl -X POST localhost:8080/api/v1/collections -d '{"name":"mini","dimensions":384}'
curl -X POST localhost:8080/api/v1/collections -d '{"name":"large","dimensions":1536}'

Key Options

RAN DDD Context

Bounded Context: Data Infrastructure

References

• API reference: See references/commands.md
• Full README
• npm