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

> Learn to set up and use the VelesDB REST API server. This guide covers Axum-based vector database operations via HTTP, installation with Cargo, Docker, or source, and OpenAPI documentation.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/main.rs) (lines 30-42):

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/main.rs) (lines 57-59).

### Custom Ports and Data Directories

Override defaults using command-line flags:

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

```

### Enable Verbose Logging

Set the `RUST_LOG` environment variable to adjust tracing levels:

```bash
RUST_LOG=info velesdb-server

```

**Important limitation**: As noted in [`src/main.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/types.rs).

### Collection Management

Create and manage vector collections through endpoints implemented in [`src/handlers/collections.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/collections.rs). Collections define the dimensionality and distance metric for stored vectors.

```bash

# 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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/points.rs). Points consist of an ID, vector array, and optional payload metadata.

```bash

# 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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/search.rs). The `SearchRequest` type (defined in [`src/types.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/src/types.rs), lines 91-115) supports filtering and top-k configuration.

```bash

# 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.

```bash

# 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.

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/query.rs).

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/graph/handlers.rs). The underlying `GraphService` ([`src/handlers/graph/service.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/graph/service.rs)) maintains edges in memory.

```bash

# 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.

```bash

# 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`](https://github.com/cyberlife-coder/velesdb/blob/main/Cargo.toml).

## Server Architecture

The VelesDB REST API server initializes two distinct state objects in [`src/main.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/collections.rs)), point operations ([`src/handlers/points.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/points.rs)), multiple search modes ([`src/handlers/search.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/src/handlers/search.rs)), and VelesQL queries ([`src/handlers/query.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main//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`](https://github.com/cyberlife-coder/velesdb/blob/main/src/main.rs) (lines 30-42).

### Does the graph data persist when the VelesDB server restarts?

No. According to [`src/main.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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.