/v1/admin
Operational endpoints — health, readiness, metrics, version, and maintenance jobs.
curl -X GET "https://example.com/v1/admin/health"Response Body
application/json
application/json
curl -X GET "https://example.com/v1/admin/ready"{ "ready": true, "checks": { "data_dir_writable": { "ok": true, "detail": "string" }, "storage": { "ok": true, "detail": "string" } }, "embedding_provider": "string", "degraded": true}Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Response Body
curl -X GET "https://example.com/v1/admin/metrics"curl -X GET "https://example.com/v1/admin/version"Health and readiness
curl https://api-v1.cortexdb.ai/v1/admin/health
# {"status":"healthy","version":"v0.9.9"}Health is a minimal liveness check
GET /v1/admin/health returns only { status, version } (version has a v prefix) — no storage,
no uptime_secs. It always returns 200 while the process is up, so orchestrators should probe
readiness instead. Health and ready are unauthenticated.
GET /v1/admin/ready → an outcome-based readiness report (verified live on v0.9.9):
{
"ready": true,
"degraded": true,
"embedding_provider": "mock::1536",
"checks": {
"data_dir_writable": { "ok": true, "detail": "ok" },
"storage": { "ok": true, "detail": "wal_events=0, vectors=0" },
"embeddings": { "ok": false, "mock": true, "unproven": true,
"ok_count": 0, "fail_count": 0,
"last_success_ms": null, "last_failure_ms": null, "last_error": null,
"detail": "pinned to mock embeddings; recall quality is not representative" },
"enrichment": { "ok": true, "enabled": false, "mode": "off",
"detail": "enrichment OFF: facts, beliefs and concepts will stay empty" },
"content_processors":{ "ok": false, "configured": [],
"detail": "NO content processors: uploaded blobs are stored but nothing is extracted" }
}
}Readiness reports what real provider calls actually did
The embeddings check is outcome-based, distinguishing three states: unproven (booted, nothing
embedded yet — not degraded), failing (fail_count rising because the most recent real call
failed — e.g. an expired/rate-limited key returning 401, with last_error carrying the provider's own
text), and healthy. degraded is true for mock or failing embeddings, so a broken key surfaces
on the wire instead of silently returning empty recall. enrichment reports ok: true when off (a
valid choice), and content_processors flags that blob uploads won't be extracted when none are
configured. Point container healthchecks and monitoring at ready, not health.
Metrics
The default metrics format is JSON, not Prometheus text
GET /v1/admin/metrics (no ?format) returns a JSON snapshot:
{ requests_total, requests_active, errors_total, uptime_seconds, version, endpoints[…], errors_by_code, writes, indexer, storage{ breakdown }, vector_indexes, process, wal, code }. The v1
docs' Prometheus cortex_* text counters are not emitted by default. (?format=json is also
accepted.) vector_indexes confirms the HNSW quantization default is TQ2.
GET /v1/admin/version → { version, crate_version, git_sha, built_at }.
Maintenance and stats
GET /v1/admin/layers/stats→ a rich operator snapshot keyedby_scopewith build counters, plusbitemporal,global, and ahealthblock (enrichment_llm_usage,layer_sources,llm_roles,provider_health). It is not the v1 docs'{ snapshot_at, per_tenant }shape.POST /v1/admin/index-audit { repair, scope }→200— a WAL↔index self-audit (both fields optional; response includesmissing_vectors,vectors_repaired,repaired_from_wal).POST /v1/admin/scopes/migrate { from, to, mode, dry_run }→202{ job_id, status, status_url }— the copy/move migration workflow.
compact and flush-views return 404
POST /v1/admin/compact and POST /v1/admin/flush-views → 404 on v0.9.9 (unshipped or renamed).
POST /v1/scopes/prune (see Scopes) works.