Skip to main content

API Reference

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

Authentication

If VCAL_AUTH_REQUIRED=1, include an API key header in protected requests:

X-VCAL-Key: <your_key>

or:

Authorization: Bearer <your_key>
  • App keys allow data-plane operations such as /v1/search, /v1/qa, /v1/insert, /v1/upsert, and /v1/delete.
  • Admin keys allow management operations such as /v1/snapshot/save, /v1/answers/save, and /v1/license/status.
  • /healthz is public.
  • /metrics may be public when VCAL_ALLOW_METRICS_WITHOUT_AUTH=1.
  • /readyz is protected when authentication is required.

Health & Readiness​

GET /healthz​

Liveness probe. Does not require authentication.

Status Codes

  • 200 — healthy
  • 5xx — unhealthy

GET /readyz​

Readiness probe. Requires an app or admin key when VCAL_AUTH_REQUIRED=1.

Status Codes

  • 200 — ready
  • 401 — missing or invalid key when authentication is required
  • 5xx — not ready

Cache Operations​

POST /v1/insert​

Insert a new vector and answer.

Request

{
  "ext_id": 900001,
  "vector": [0.001, 0.001],
  "answer": "VCAL local test answer"
}

The vector length must match VCAL_DIMS.

Response

{ "ok": true }

POST /v1/upsert​

Insert or replace a vector and answer for an existing external ID.

Request

{
  "ext_id": 900001,
  "vector": [0.001, 0.001],
  "answer": "Updated answer"
}

Response

{ "ok": true }

POST /v1/search​

Search for nearest cached vectors.

Request

{
  "query": [0.001, 0.001],
  "k": 1
}

Response

{
  "hits": [
    { "id": 900001, "distance": 0.0 }
  ]
}

POST /v1/qa​

Query the semantic cache and return the cached answer when the similarity threshold is met.

Request

{
  "query": [0.001, 0.001],
  "k": 1,
  "sim_threshold": 0.7
}

Hit response

{
  "hit": true,
  "id": 900001,
  "distance": 0.0,
  "similarity": 1.0,
  "answer": "VCAL local test answer"
}

Miss response

{
  "hit": false,
  "id": null,
  "distance": null,
  "similarity": null,
  "answer": null
}

POST /v1/delete​

Delete an entry by external ID. Deletions are tombstoned so deleted records do not return after restart.

Request

{ "ext_id": 900001 }

Response

{ "deleted": true, "ok": true }

Snapshots: Index + Answers + Tombstones​

VCAL Semantic Cache v0.6.0 persists three paired artifacts under the configured data directory:

  • vcal.index — HNSW vector index, Envelope v1 format
  • answers.json — cached answer payloads and metadata
  • tombstones.json — deleted IDs that must remain hidden after restart

Runtime autosave and manual snapshot saves are background-safe in v0.6.0:

  1. VCAL acquires the cache-state read lock.
  2. VCAL serializes a consistent in-memory snapshot bundle.
  3. The read lock is released.
  4. Snapshot files are written without entering drain mode.

Graceful shutdown still uses the quiescent path: the server enters drain mode, waits for in-flight work, and writes the final paired snapshot before exit.

POST /v1/snapshot/save​

Save the paired snapshot set. Requires an admin key when authentication is enabled.

Request

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

Response

{
  "ok": true,
  "path": "/var/lib/vcal/data/vcal.index",
  "bytes": 5043,
  "unixtime": 1780248258
}

POST /v1/snapshot/load​

Load a 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. In normal operation, prefer /v1/snapshot/save so index, answers, and tombstones stay paired.

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

  • Snapshot paths are resolved relative to the configured data directory unless an absolute path is supplied by the server configuration.
  • atomic: true performs a safe write using a temporary file and rename.
  • If VCAL_AUTOSAVE_SECS > 0, autosave periodically persists the paired snapshot set.
  • Server startup automatically restores paired artifacts if valid files are present.

License Status​

GET /v1/license/status​

Return the active license status. Requires an admin key when authentication is enabled.

Response

{
  "valid": true,
  "tier": "growth",
  "org": "VCAL Labs",
  "days_until_expiry": 165
}

Metrics​

GET /metrics​

Prometheus-compatible metrics endpoint. Returns plaintext exposition format.

Common metrics include:

  • vcal_active_ids
  • vcal_answers_cached
  • vcal_search_requests_total
  • vcal_search_errors_total
  • vcal_insert_requests_total
  • vcal_insert_errors_total
  • vcal_cache_hits_total
  • vcal_cache_misses_total
  • vcal_tokens_saved_total
  • vcal_snapshot_saves_total
  • vcal_license_days_until_expiry

GET /api-docs​

Opens the built-in Swagger UI when the image/binary is built with the Swagger UI feature.

Admin Notes​

  • Admin endpoints are exposed under /v1/*, not /admin/*.
  • Admin-only endpoints require an admin key if VCAL_AUTH_REQUIRED=1.
  • VCAL Core is open-source under Apache-2.0.
  • VCAL Semantic Cache is distributed under a commercial EULA with license enforcement.