Skip to main content

API Reference

Base URL: http://<host>:8080

Authentication
If VCAL_AUTH_REQUIRED=1, include an API key header in all requests (except /metrics, /healthz, and /readyz):

X-VCAL-Key: <your_key>

or (alternatively)

Authorization: Bearer <your_key>
  • App keys allow data-plane ops (/v1/search, /v1/qa, /v1/upsert, etc.)
  • Admin keys allow management ops (/v1/snapshot/*, /v1/answers/*)
  • Unlicensed or expired keys return 403 Forbidden.

Endpoints​

POST /v1/qa​

Query VCAL’s semantic cache for a vector match.
If a match (similarity ≥ threshold) exists, returns the cached answer.

Request

{ "q": "What is VCAL Server?", "embedder": "nomic-embed-text" }

Response

{
  "ok": true,
  "cached": true,
  "similarity": 0.93,
  "answer": "VCAL Server is a semantic cache for LLMs..."
}

Snapshots (Index + Answers)​

VCAL persists two paired artifacts under ./data/ by default:

  • vcal.index — the HNSW vector index (Envelope v1 format)
  • answers.json — the answer store (Q→A payloads and metadata)

Both support explicit save/load endpoints and also autosave if configured.

Note
As of v0.5.5, the index file uses the Envelope v1 structured format:

{
  "format": "vcal-hnsw",
  "version": 1,
  "meta": { "dims": 768, "m": 32, "ef": 128, "efc": 200 },
  "hnsw": { ... }
}

POST /v1/snapshot/save​

Save both the index and answers to disk atomically.

Request

{ "path": "vcal.index", "atomic": true }

Response

{ "ok": true, "path": "./data/vcal.index", "bytes": 1048576, "unixtime": 1725043200 }

POST /v1/snapshot/load​

Load the previously saved index into memory.

Request

{ "path": "vcal.index" }

Response

{ "ok": true, "path": "./data/vcal.index", "vectors": 1000000 }

POST /v1/answers/save​

Save the answer store to disk.

Request

{ "path": "answers.json", "atomic": true }

Response

{ "ok": true, "path": "./data/answers.json", "bytes": 262144, "unixtime": 1725043200 }

POST /v1/answers/load​

Load answers back into memory.

Request

{ "path": "answers.json" }

Response

{ "ok": true, "path": "./data/answers.json", "answers": 42000 }

Notes

  • All paths are resolved relative to the local ./data directory.
  • atomic: true performs a safe write (temp file → rename).
  • If VCAL_AUTOSAVE_SECS > 0, autosave periodically persists both files.
  • Server startup automatically restores paired artifacts if found valid.

GET /metrics​

Prometheus-compatible metrics endpoint. Returns plaintext exposition format.

Status Codes

  • 200 — success
  • 5xx — internal error

Health & Readiness​

GET /healthz​

Liveness probe. Returns no body when healthy.

Status Codes

  • 204 No Content — healthy
  • 5xx — unhealthy

GET /readyz​

Readiness probe (index loaded and accepting requests). Returns no body when ready.

Status Codes

  • 204 No Content — ready
  • 5xx — not ready

If you prefer JSON bodies such as { "ok": true }, track this as a feature request.
Current builds intentionally return empty bodies for performance reasons.

GET /api-docs​

Opens the built-in Swagger UI for live testing.

Admin Notes​

  • Snapshots and answers persist under ./data/.
  • Admin-only endpoints require an Admin key if VCAL_AUTH_REQUIRED=1.
  • VCAL Core is open-source under Apache-2.0.
  • VCAL Server (Pro edition) is distributed under a commercial EULA with license-key enforcement.