smartbotic-vectorapi

smartbotic-vectorapi

A general-purpose, client-agnostic REST API in front of smartbotic-database for storing data from automation workflows. It stores RAG embedding vectors (with cosine similarity search) and arbitrary JSON documents, organized into projects (isolated namespaces) and protected by API keys with per-project grants.

n8n workflows are the primary client, but any HTTP client can use it. A React admin console ships alongside.

• Multi-project — collections live in isolated project namespaces, addressed as a URL path segment (/api/v1/projects/{project}/...), like MySQL databases.
• Multi-key auth — each API key is granted access to one or more projects (or all, *); admin keys manage projects and keys. Bearer-token for the API; cookie session for the web UI.
• RAG — store a precomputed vector, or send text and have it embedded via OpenAI; then run cosine similarity search.
• Per-project embedding providers — a project can override the endpoint, API key and model, so each customer's embedding usage meters against their own provider key. Precedence: collection model pin, then project override, then the global default.
• JSON CRUD — full create/read/update/patch/delete with filtered find.
• Dynamic config — only a minimal bootstrap config.json on disk; everything else (keys, OpenAI settings, CORS, etc.) lives in the database and hot-reloads without a restart.
• Self-describing — GET /openapi.json (OpenAPI 3.1), GET /llms.txt (agent-friendly summary), and a rendered docs page at /docs.

Architecture

  n8n / clients ──HTTP+Bearer──┐
                               ▼
  admin browser ──cookie──▶ smartbotic-vectorapi ──gRPC──▶ smartbotic-database
                               │  (libsmartbotic-db-client)
                               └──HTTPS──▶ api.openai.com/v1/embeddings

The server is C++20 (cpp-httplib, OpenSSL). Project multi-tenancy is threaded at the gateway boundary via qualify(project, collection); authorization (key → project grants) is the API's own layer. The web UI is React 19 + Vite + TypeScript + TailwindCSS + Monaco, served by the same binary (same-origin) or via the Vite dev proxy.

Component	Path
Server	src/ → smartbotic-vectorapi binary
Web UI	webui/ (React) → built assets
API spec	api/openapi.json, api/llms.txt
Packaging	packaging/ (Debian .deb, systemd, Docker)
Design + plans	docs/superpowers/specs/, docs/superpowers/plans/
API reference	docs/api.md

Install (Debian 13 / trixie)

The packages are published to the smartbotics apt repository.

# one-time repo setup (see /data/dev/smartbotics/smartbotics-deb-repo for credentials)
curl -fsSL https://repository.smartbotics.ai/add-repo.sh | sudo bash -s -- --user <user> --password <pass>

sudo apt update
sudo apt install smartbotic-vectorapi smartbotic-vectorapi-webui

On first start the service generates an admin API key and logs it once:

journalctl -u smartbotic-vectorapi | grep "Generated initial admin API key"

Optionally seed secrets before first boot in /etc/smartbotic-vectorapi/vectorapi.env:

SMARTBOTIC_VECTORAPI_KEY=<your-admin-key>     # seed the admin key instead of auto-generating
OPENAI_API_KEY=sk-...                          # enables text→embedding generation for RAG

The service listens on :8080 (configurable). The web console is at http://<host>:8080/; the rendered API docs are at /docs.

Build from source

Requires: cmake, ninja, g++ (C++20), pkg-config, libsmartbotic-db-client-dev (>= 2.3.0), nlohmann-json3-dev, libspdlog-dev, libssl-dev, libsystemd-dev, and nodejs/npm (for the web UI). cpp-httplib is fetched via CMake.

# backend + web UI
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_WEBUI=ON -S .
cmake --build build -j"$(nproc)"

# run the tests (needs a running smartbotic-database on localhost:9004 for the integration tests)
cmake -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_WEBUI=OFF -S . && cmake --build build && ctest --test-dir build

# run locally (point --webui-dir at the built assets)
SMARTBOTIC_VECTORAPI_KEY=dev ./build/src/smartbotic-vectorapi \
  --config config/config.json --share-dir "$PWD/api" --webui-dir "$PWD/build/webui/dist"

The web UI alone:

cd webui && npm install && npm run dev      # dev server on :3000, proxies /api + /ui to :8080
cd webui && npm run build                   # production build → dist/

Packaging

./packaging/build.sh --local                 # native .debs for the current system → dist/local/
./packaging/build.sh                          # Debian-13 .debs via Docker → dist/debian13/
./packaging/build.sh --repo --suite trixie --sync   # build + publish to repository.smartbotics.ai

Produces two packages: smartbotic-vectorapi (server + systemd unit + config + openapi.json/llms.txt + rendered /docs) and smartbotic-vectorapi-webui (the built admin console).

Quick API tour

KEY=<admin-key>; BASE=http://localhost:8080

# create a project + a vector collection (OpenAI text-embedding-3-small = 1536 dims)
curl -s -X POST $BASE/api/v1/projects -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"name":"acme"}'
curl -s -X POST $BASE/api/v1/projects/acme/collections -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"memories","kind":"vector","vector_dimension":1536,"embedding_model":"text-embedding-3-small"}'

# point this project at its own embedding provider (its own key gets metered)
curl -s -X PUT $BASE/api/v1/projects/acme/settings/embeddings -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"openai_api_base":"https://api.openai.com","openai_api_key":"sk-acme","default_embedding_model":"text-embedding-3-small"}'

# store a RAG item from text (embedded server-side) and search it
curl -s -X POST $BASE/api/v1/projects/acme/collections/memories/vectors -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"text":"the user prefers dark mode","metadata":{"src":"n8n"}}'
curl -s -X POST $BASE/api/v1/projects/acme/collections/memories/search -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"query_text":"dark mode","top_k":5}'

Full reference: docs/api.md, the live /docs page, and GET /openapi.json.

License

Proprietary — Smartbotics AI.