HTTP API: health

Whether what this process serves is healthy, decided by the engines that already decide it: the index's diagnostics, the registry builder, the benchmark projection's coverage, the comparison `generate --check` makes and the lease reading `server.status` answers from. No check here has an opinion of its own.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

health

GET /api/v1/health health.report

Health of this process

Every dimension of what this process serves — the layer as it was read, the registry, the scope, version control, benchmark coverage, the committed registry manifest, the shared server of this checkout and the attached peers — each decided by the engine that owns it, with the command that reproduces the verdict.

query
behaviorally_verified
benchmark required
cache process (max_entries=4, ttl_seconds=5)
MCP tool majordomus_health
MCP resource {"name": "health", "uri": "majordomus://health"}

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/health"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Health	Health of this process: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/live health.live

Liveness

Is this process alive: the cheapest true statement this executable can make about itself, with the version that answered. No filesystem traversal, no index build, no network — this is what a hosting platform polls, and it must cost nothing to say.

query
behaviorally_verified
benchmark required
cache disabled

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/live"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Liveness	Liveness: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/ready health.ready

Readiness

Can this process serve traffic: the registry and the index it built at start-up, already resident, and how the layer read. Only local initialisation — never an external provider, a database or another service, because a readiness check that probes a dependency fails a deployment for something that is not this process.

query
behaviorally_verified
benchmark required
cache disabled

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/ready"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Readiness	Readiness: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

Health

object

The health of what this process serves.

property	type	required	description
status	HealthStatus → HealthStatus	yes	The worst check's status.
repository	HealthStatus → HealthStatus	yes	The worst status among the dimensions that describe the repository at this commit: every check but the ones in `PROCESS_DIMENSIONS`. A process that is no server — the command line, or the reader of a published snapshot (ADR 0141) — cannot decide who is attached or what the mesh runtime did, and says `unknown` for them; this is the verdict that is the same whichever process read the repository, and it is what a publication shows first.
tallies	map of integer (uint)	yes	How many checks stand where, by status word.
checks	array of HealthCheck → HealthCheck	yes	Every dimension, in a stable order.
observed	map of AnswerObservation → AnswerObservation	no	When the state a check decided on was read, by check id: the freshness contract (`crate::index::AnswerObservation`). A check absent here decided live, during this call. `layer` and `git` are here because they judge the picture the index took, which is as old as the index.

Used by health.report

HealthCheck

object

One dimension of the system, decided by one engine, with what a reader needs to check it themselves.

property	type	required	description
id	string	yes	A stable id, `[a-z][a-z0-9-]*`.
title	string	yes	The short name.
status	HealthStatus → HealthStatus	yes	Where it stands.
detail	string	yes	One line: what the engine decided and on what.
decided_by	string	yes	The engine that decided it, named so the reader knows what to fix.
evidence	array of string	no	What reproduces the verdict: a command, or a path.
findings	array of string	no	Findings behind the verdict, when the engine produced any: the diagnostic messages, the stale files, the missing coverage lines.

Used by Health

Liveness

object

The answer to "is this process alive": the cheapest true thing this executable can say about itself. Deliberately not a summary of anything — a probe that grew an opinion would stop reporting the one fact the platform polls it for.

property	type	required	description
alive	boolean	yes	Always `true`. A process that could not answer would not answer at all, which is the signal.
version	string	yes	This executable's version, so a rolling deployment can tell which build answered.
commit	string	yes	The commit this executable was built from, in full, or `unknown` when the build could not name one. A version is what a build calls itself and two revisions share it; this is what a deployment is checked against. Never omitted: an absent field would read as a server too old to say, and `unknown` is a different, truthful answer.
dirty	boolean \| null	no	Whether that commit's tree carried uncommitted changes when this executable was built; `null` when the build did not know.

Used by health.live

Readiness

object

The answer to "can this process serve traffic": the local initialisation a request would need, and nothing beyond this process. A readiness check that grew a dependency probe fails a deployment because an unrelated service is down.

property	type	required	description
ready	boolean	yes	Whether every part below is in place.
version	string	yes	This executable's version.
commit	string	yes	The commit this executable was built from, or `unknown`; the same value `health.live` answers.
dirty	boolean \| null	no	Whether the build's tree was dirty; `null` when the build did not know.
capabilities	integer (uint)	yes	How many capabilities the registry holds; zero would mean nothing to serve.
objects	integer (uint)	yes	How many objects the index holds. Read from the index this process built at start-up: it is already in memory, and reading it walks nothing.
layer	HealthStatus → HealthStatus	yes	Whether the layer read cleanly. A degraded layer is still served — the diagnostics are the point — so this reports rather than refuses.
stale	string \| null	no	Why this process is serving code that is no longer on disk: the executable it was started from has been replaced or removed since. Present, `ready` is false — a server answering with yesterday's code says so in the place it says it is ready, to a client holding nothing but this answer (I1502).
reasons	array of string	no	Every reason this answer is not a plain yes, as `code: words`. `lease_lost` and `stale` make `ready` false: another process holds this checkout's lease, or this one serves code that is gone. `layer_degraded` does not: the layer is served with its diagnostics, and a client decides whether that is enough.

Used by health.ready