Operational introspection: health, readiness, metrics, version, layer scheduler stats.

Admin Endpoints

Operational visibility. Health and readiness are unauthenticated; everything else requires diagnostics.read.

GET /v1/admin/health

Unauthenticated. Liveness only — answers 200 whenever the process is up. Alias: GET /v1/health.

{
  "status":  "healthy",
  "storage": "ok",
  "uptime_secs": 5104320,
  "version": "0.7.1"
}

For "is this node actually ready to serve traffic?", use /v1/admin/ready below — health stays 200 even when storage is unreadable or providers are degraded.

GET /v1/admin/ready

Unauthenticated. Readiness — the probe containers and orchestrators should use before admitting traffic (liveness probes stay on /v1/admin/health). Alias: GET /v1/ready.

Checks data-dir writability and that the storage handles (vector index + WAL) answer. Also reports the pinned embedding provider; degraded is true when the corpus is pinned to mock embeddings.

{
  "ready": true,
  "checks": {
    "data_dir_writable": { "ok": true, "detail": "ok" },
    "storage":           { "ok": true, "detail": "wal_events=134892, vectors=98211" }
  },
  "embedding_provider": "openai:text-embedding-3-small:1536",
  "degraded": false
}

Returns 200 when ready; 503 with the same body shape when any required check fails.

GET /v1/admin/metrics

Prometheus-style scrape (text) by default; pass ?format=json for a JSON snapshot.

HTTP/1.1 200 OK
Content-Type: text/plain; version=0.0.4

Counters include cortex_experience_total, cortex_recall_total, cortex_recall_latency_ms, cortex_pack_size_tokens, cortex_forget_total, cortex_erasure_events_deleted_total, plus per-layer + per-capability splits.

GET /v1/admin/version

{
  "version":       "0.7.1",
  "crate_version": "0.7.1",
  "git_sha":       "...",
  "built_at":      "2026-07-13T10:00:00Z"
}

GET /v1/admin/layers/stats — Experimental

Per-tenant snapshot of the auto-layer scheduler. Returns when CORTEX_V1_LAYERS_AUTO=1 is set; otherwise an empty snapshot.

{
  "snapshot_at": "2026-05-15T10:42:00Z",
  "per_tenant": {
    "acme": {
      "events_per_min":         42,
      "extract_lag_p95_ms":     312,
      "consolidate_lag_p95_ms": 1812,
      "synthesize_lag":         "P1D",
      "queue_depth":            14
    }
  }
}

POST /v1/admin/index-audit — Experimental

WAL↔search-index self-audit: finds acked events whose search-index entries are missing, and (with repair) re-indexes them. Requires diagnostics.read. Synchronous full-WAL walk — expect seconds to minutes on a large store; run it from an operator shell, not a tight-timeout request path.

{ "repair": false, "scope": "user:alice" }

Both fields optional. repair: true re-creates the missing BM25 docs and vectors from stored state — on server ≥ v0.8.7 this includes rebuilding missing content-store rows from the WAL event content itself (previously such events were unrepairable: "content row missing; cannot repair from stored state"). scope restricts the audit and the repair to one scope subtree (exact or descendant); before v0.8.7 it was accepted but silently ignored.

{
  "scanned": 1088,
  "missing": ["019f6a9e-..."],
  "missing_total": 5,
  "repaired": 5,
  "repair_failed": 0,
  "vector_repair_skipped": 0,
  "errors": []
}

vector_repair_skipped counts chunks whose BM25 doc was restored but whose vector could not be re-embedded (embedding provider down) — re-run repair once the provider recovers.

POST /v1/admin/scopes/migrate — Experimental

The scope migration/merge workflow (server ≥ v0.8.13): applications that change their memory model — e.g. per-source scopes user:x/source:chatgpt folding into one unified user:x — get a first-class copy/move instead of hand-rolled re-sync scripts. Requires admin.compact.

{ "from": "user:x/source:chatgpt", "to": "user:x",
  "mode": "copy", "dry_run": false, "confirm_erase_source": false }

Returns 202 {job_id, status_url}; poll GET /v1/admin/scopes/migrate/{job_id} (job records are process-local, like erasure jobs). Events copy through the normal write path with event_time, content, and metadata preserved; destination ids are deterministic, so re-running resumes and never duplicates. [triple] events regenerate their deterministic facts under the target synchronously; other derived layers regenerate via the deployment's normal enrichment/synthesis (enrichment-off deployments: trigger POST /v1/understanding/synthesize on the target). mode: "move" erases the source through the standard scope-wide forget — only after a clean, count-verified copy and an explicit confirm_erase_source: true; any verification failure leaves the source untouched with the reason in the job record. Migrates the exact scope string only — migrate a subtree by calling once per scope.

Maintenance — Experimental

POST /v1/admin/compact         # RocksDB compaction nudge
POST /v1/admin/flush-views     # Flush in-memory view caches
POST /v1/scopes/prune          # Garbage-collect auto-provisioned scopes

All X-Cortex-Stability: experimental. Require operator-tier capability; deny by default in cloud_shared_saas.