--- title: "Health Ready" method: GET path: "/api/v1/health/ready" tags: ["memory-v1"] --- # Health Ready `GET /api/v1/health/ready` ## Request - Base URL: `https://core.mnemoverse.com` - URL: `https://core.mnemoverse.com/api/v1/health/ready` - Auth: none required Deep readiness check. ``ready`` = database AND engine (the hard dependencies) → HTTP 503 when false, so an orchestrator healthcheck (Railway) refuses to promote a build whose startup failed (FAILURE-SURFACE P0-4: the old contract was HTTP 200 with ``ready: false`` in the body, which promoted broken builds). ``checks.warm`` is reported to every caller: True when the warm-up is disabled, its readiness gate (`Settings.concept_expander_warm_ready_gate_seconds`, 0 = off by default) is 0, THIS process's warm run has finished, or the gate's time cap has elapsed. It turns ``ready`` false, and the answer into a 503, ONLY for the orchestrator's deploy healthcheck (`_is_deploy_healthcheck`: Railway probes from `healthcheck.railway.app`, at the start of a deployment only), because holding traffic promotion is the gate's one purpose. A process restarted after a crash takes traffic with no healthcheck at all, so every other reader is asking about a process that is already serving and gets ``ready: true`` with ``checks.warm: false``. The wait is bounded by the cap in every case, including a warm run that never starts. See `_resolve_warm_check`. ``checks.embedding`` is a LIVE vendor call (cached 60 s — see ``_probe_embedding``). It does NOT gate ``ready``: a dead embedding vendor yields HTTP 200 with ``degraded: true`` so the fix for a vendor outage can still be deployed *during* the outage, and external probes alert on ``degraded`` instead. Probes must assert ``ready && !degraded``. ## Response `200` Successful Response - ReadyResponseSchema: Deep readiness check (DB + engine + concept-expander warm-up + embedding vendor). Two verdicts, deliberately separate (FAILURE-SURFACE 2026-08-26, P0-3/P0-4): * ``ready`` - the hard dependencies (database, engine). ``false`` is served as **HTTP 503**, so an orchestrator healthcheck refuses to promote a build whose startup failed. For the orchestrator's deploy healthcheck ONLY, a warm-up still inside its gate also makes ``ready`` false (see below). * ``degraded`` — ``ready`` but the LIVE embedding probe failed. Served as **HTTP 200**, so a vendor outage never blocks deploying its own fix. External probes must assert ``ready == true && degraded == false``. ``checks.embedding`` is a real vendor call (cached 60 s server-side, probe text time-bucketed to defeat the embedding LRU), not a wiring check. ``checks.warm`` is reported to every caller and is bounded: with the warm-up enabled and its readiness gate (`CONCEPT_EXPANDER_WARM_READY_GATE_SECONDS`, max 200) set positive, it is false while the current process's warm run is still inside the window. It makes ``ready`` false (HTTP 503) only for a probe whose `Host` is `CONCEPT_EXPANDER_WARM_READY_GATE_HOST` (default `healthcheck.railway.app`, Railway's deploy healthcheck), so that traffic promotion waits for the warm-up. Every other caller keeps getting ``ready: true``: after a crash restart the process serves traffic at once, and reporting it as not ready would report an outage that is not happening. Never longer than the cap, and never at all with the gate at its default of 0 or the warm-up disabled. - `ready` boolean, required: True when the hard dependencies (database, engine) are operational. For the orchestrator's deploy healthcheck only, also false while the bounded concept-expander warm-up gate is holding - see `checks.warm`. False is served as HTTP 503. Does NOT include the embedding probe — see `degraded`. - `degraded` boolean: True when `ready` is true but the live embedding probe failed (`checks.embedding == false`). Served as HTTP 200 so a vendor outage cannot block a deploy; probes must alert on it. - `checks` object, required: Per-subsystem status. `database`: live SELECT 1; `engine`: initialised; `embedding`: live embed call succeeded within the timeout (cached 60 s); `warm`: true when the concept-expander warm-up readiness gate is off (disabled, or `CONCEPT_EXPANDER_WARM_READY_GATE_SECONDS == 0`, the default), the warm-up has finished, or the gate's time cap has elapsed - false only while a gated warm-up is still inside its window (including a just-started instance whose warm run has not begun yet). - `embedding_checked_at` string, nullable: ISO-8601 UTC timestamp of the live embedding call behind `checks.embedding` (may be up to 60 s old — the probe is cached). None when the engine is not initialised. - `embedding_error` string, nullable: Exception CLASS name of the last failed embedding probe (e.g. 'TimeoutError', 'HTTPStatusError'), or a short reason token ('embed_fn_not_wired'). Never the message — messages may carry URLs or credentials. None when the probe succeeded or the engine is not initialised. - `version` string, required: Application version string. - `git_sha` string: Git commit SHA of the running build (injected at image build time; 'unknown' for local/dev). The post-deploy smoke compares this against the merged commit so a frozen OLD instance cannot report false-green. - `embedding_identity` EmbeddingIdentitySchema: Resolved GLOBAL embedding identity — the server-truth for provenance stamping. Exposes ONLY the model id and effective dimension (model names are not secrets); never api_url, key material, or backend internals. - `model` string, required: Model id of the actual producing global EmbeddingService. - `dim` integer, required: Effective output dimension (post-Matryoshka truncation). ## Other responses - `400`: Validation error - `401`: Unauthorized - `403`: Forbidden - `404`: Not found - `429`: Rate limited - `500`: Internal server error - `503`: Not ready: database or engine is down, or the (bounded) concept-expander warm-up gate has not yet opened (same body, `ready: false`). --- [API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)