How to Set Up and Use the VelesDB REST API Server: A Complete Guide

The VelesDB REST API server is a lightweight (~15MB) Axum-based binary that exposes full-featured vector database operations via HTTP, installable via cargo, Docker, or source build, and serves an OpenAPI-documented interface on port 8080 by default.

The VelesDB server provides a production-ready HTTP layer for the VelesDB vector database, implemented in Rust using the Axum web framework. According to the cyberlife-coder/velesdb source code, the server combines persistent vector storage with an in-memory graph service, auto-generating OpenAPI specifications via Utoipa for immediate API discoverability. This guide covers installation, configuration, and practical usage of the VelesDB REST API server using actual implementation details from the codebase.

Installation Methods

The VelesDB REST API server can be deployed through three primary distribution channels. Each method installs the same velesdb-server binary but suits different deployment scenarios.

Install from crates.io

The simplest installation uses Rust's package manager to place the binary in your local cargo bin directory.

cargo install velesdb-server

After installation, the binary is available at ~/.cargo/bin/velesdb-server. Ensure your PATH includes the cargo bin directory to run the command from any location.

Deploy with Docker

For containerized environments, the official image exposes port 8080 and expects a mounted volume for persistent data storage.

docker run -p 8080:8080 -v ./data:/data ghcr.io/cyberlife-coder/velesdb:latest

The container automatically executes the server with default arguments. Mount a host directory to /data to prevent vector store loss when the container restarts.

Build from Source

Clone the repository and compile the release binary to access the latest features or customize the build.

git clone https://github.com/cyberlife-coder/VelesDB
cd VelesDB
cargo build --release -p velesdb-server

The optimized binary appears at target/release/velesdb-server. This method requires the Rust toolchain and takes longer due to compilation, but provides full control over feature flags like optional Prometheus metrics.

Running the Server

The VelesDB REST API server boots via src/main.rs, which parses CLI arguments, initializes the persistent Database, creates the in-memory GraphService, and composes the Axum router before binding to the configured address.

Default Configuration

Launch the server without arguments to use the built-in defaults defined in src/main.rs (lines 30-42):

velesdb-server

This configuration uses ./data for persistent storage, binds to 0.0.0.0, and listens on port 8080. During startup, logs indicate the data directory path and listening address as implemented in src/main.rs (lines 57-59).

Custom Ports and Data Directories

Override defaults using command-line flags:

velesdb-server --port 9000 --data ./my_vectors

Enable Verbose Logging

Set the RUST_LOG environment variable to adjust tracing levels:

RUST_LOG=info velesdb-server

Important limitation: As noted in src/main.rs (lines 64-68), the GraphService is currently in-memory only. Any edges or graph relationships added via the REST API will disappear when the server process restarts, while vector collections persist to disk.

Core REST API Operations

All endpoints are relative to the base server address (e.g., http://localhost:8080). The implementation splits handlers across specialized modules in src/handlers/, with request/response types defined in src/types.rs.

Collection Management

Create and manage vector collections through endpoints implemented in src/handlers/collections.rs. Collections define the dimensionality and distance metric for stored vectors.

# Create a collection with 768 dimensions and cosine similarity

curl -X POST http://localhost:8080/collections \
     -H "Content-Type: application/json" \
     -d '{"name":"documents","dimension":768,"metric":"cosine"}'

# List all collections

curl http://localhost:8080/collections

# Retrieve collection metadata

curl http://localhost:8080/collections/documents

# Delete a collection permanently

curl -X DELETE http://localhost:8080/collections/documents

Point Operations

Insert, update, or delete vector points within collections via src/handlers/points.rs. Points consist of an ID, vector array, and optional payload metadata.

# Upsert vectors with payload metadata

curl -X POST http://localhost:8080/collections/documents/points \
     -H "Content-Type: application/json" \
     -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3],"payload":{"title":"Introduction"}}]}'

# Delete specific points by ID

curl -X DELETE http://localhost:8080/collections/documents/points \
     -H "Content-Type: application/json" \
     -d '{"ids":[1,2,3]}'

Vector Search

Perform similarity search using the HNSW index through endpoints in src/handlers/search.rs. The SearchRequest type (defined in src/types.rs, lines 91-115) supports filtering and top-k configuration.

# Basic similarity search with metadata filtering

curl -X POST http://localhost:8080/collections/documents/search \
     -H "Content-Type: application/json" \
     -d '{"vector":[0.15,0.25,0.35],"top_k":5,"filter":{"category":{"$eq":"tech"}}}'

Full-Text and Hybrid Search

Execute BM25 full-text searches or combine vector similarity with keyword matching for hybrid retrieval.

# BM25 text search

curl -X POST http://localhost:8080/collections/documents/search/text \
     -H "Content-Type: application/json" \
     -d '{"query":"rust programming","top_k":10}'

# Hybrid search (vector + text fusion)

curl -X POST http://localhost:8080/collections/documents/search/hybrid \
     -H "Content-Type: application/json" \
     -d '{"vector":[0.15,0.25,0.35],"query":"rust programming","top_k":10}'

Multi-Query Fusion

For RAG applications, submit multiple vectors simultaneously and fuse results using Reciprocal Rank Fusion (RRF) or other strategies.

curl -X POST http://localhost:8080/collections/documents/search/multi \
     -H "Content-Type: application/json" \
     -d '{"vectors":[[0.1,0.2,0.3],[0.3,0.4,0.5]],"top_k":10,"fusion":"rrf","fusion_params":{"k":60}}'

VelesQL Queries

Execute declarative queries via the VelesQL parser (core crate) exposed through src/handlers/query.rs.

curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"query":"SELECT * FROM documents WHERE VECTOR NEAR $v LIMIT 5","params":{"v":[0.15,0.25,0.35]}}'

Graph Operations (Preview)

Manage relationships and traverse connections through the graph API implemented in src/handlers/graph/handlers.rs. The underlying GraphService (src/handlers/graph/service.rs) maintains edges in memory.

# Add a directed edge with properties

curl -X POST http://localhost:8080/collections/documents/graph/edges \
     -H "Content-Type: application/json" \
     -d '{"id":123,"source":1,"target":2,"label":"authored_by","properties":{"role":"author"}}'

# List edges filtered by label

curl http://localhost:8080/collections/documents/graph/edges?label=authored_by

# Graph traversal (BFS or DFS)

curl -X POST http://localhost:8080/collections/documents/graph/traverse \
     -H "Content-Type: application/json" \
     -d '{"source":1,"strategy":"bfs","max_depth":3,"limit":100,"rel_types":["authored_by"]}'

Health Checks and Documentation

Access operational metadata and interactive documentation without authentication.

# Health check endpoint

curl http://localhost:8080/health

# OpenAPI specification JSON

curl http://localhost:8080/api-docs/openapi.json

# Swagger UI (browse to this URL)

http://localhost:8080/swagger-ui

The Prometheus metrics endpoint (/metrics) is available only when compiling with the prometheus feature flag, as defined in Cargo.toml.

Server Architecture

The VelesDB REST API server initializes two distinct state objects in src/main.rs: a persistent Database for vector storage and a transient GraphService for relationship management. The Axum router composition merges a standard API router (state = AppState from src/lib.rs) with a separate graph router (state = GraphService), then applies CORS, tracing, and optional Prometheus middleware layers before binding to the configured host and port.

Summary

• Installation flexibility: Deploy the VelesDB REST API server via cargo install, Docker, or source compilation depending on your infrastructure requirements.
• Default configuration: The server binds to 0.0.0.0:8080 with data stored in ./data unless overridden by CLI arguments (--port, --data).
• API surface: Access collection management (src/handlers/collections.rs), point operations (src/handlers/points.rs), multiple search modes (src/handlers/search.rs), and VelesQL queries (src/handlers/query.rs) through standardized REST endpoints.
• Graph limitations: The graph API (src/handlers/graph/*) operates on in-memory state only; edges do not persist between server restarts, unlike vector collections.
• Documentation: Utoipa-generated OpenAPI specs and Swagger UI are served at /api-docs/openapi.json and /swagger-ui respectively for immediate API exploration.

Frequently Asked Questions

How do I change the default port for the VelesDB REST API server?

Pass the --port flag when launching the binary. For example, velesdb-server --port 9000 binds the HTTP listener to port 9000 instead of the default 8080, as implemented in the CLI argument parser within src/main.rs (lines 30-42).

Does the graph data persist when the VelesDB server restarts?

No. According to src/main.rs (lines 64-68), the GraphService is strictly in-memory. While vector collections persist to the configured data directory (default ./data), all edges and graph relationships are lost when the server process terminates.

Where can I find the OpenAPI specification for the VelesDB REST API?

The server auto-generates documentation using Utoipa macros defined in src/lib.rs (lines 57-67). Access the raw JSON specification at http://localhost:8080/api-docs/openapi.json or the interactive Swagger UI at http://localhost:8080/swagger-ui when the server is running.

What is the difference between installing velesdb-server and the core library?

The velesdb-server crate (installed via cargo install velesdb-server) is the standalone HTTP binary containing all REST handlers (src/handlers/*), while the core library provides the underlying vector database engine. Install the server binary to expose database functionality via REST; use the core library directly for embedded Rust applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}