HTTP API: monitor

Everything that happens around this repository, followed in one stream: the mesh journal (sessions on every linked machine, this checkout's board among them, their claims, handovers and reviews), the executor's trail (merges, refreshes, repairs, closures, failures) and GitHub (pull requests opened, merged and closed, finished workflow runs), folded so that a session re-announcing itself unchanged and a step that decided nothing are counted rather than shown, with what is addressed to the reader marked (ADR 0133).

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.

monitor

GET /api/v1/monitor monitor.stream

Follow everything in one stream

A page of signals after a cursor, oldest first, or without one the newest of the last `since` seconds: each with its time, source, kind, severity, machine, session, actor, pull request, branch, issue, paths, a one-line summary and whether it is for the reader. Re-projections and undecided steps are counted as `suppressed`; a source that cannot be read is listed with its reason, never answered as empty. The page's `cursor` is the next page's `after`, and nothing on this page comes back. Reads only.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_monitor

Query parameters

name	type	required	description	examples
after	string	no	The `cursor` of the previous page; without it, the page is the newest signals of the last `since` seconds.	local-resumed: "x0"
limit	integer (uint64)	no	At most this many signals (default 50, at most 500).	local-first-page: 50local-resumed: 20
sources	string	no	A comma-separated subset of `mesh`, `executor` and `github` (default: all three).	local-first-page: "mesh,executor"local-resumed: "mesh,executor"
for	string	no	Comma-separated names of the reader — a worker (`1b`), a role, a login — so that what is addressed to it is marked `for_you`. An MCP caller is also its own board session.	local-first-page: "1b"local-resumed: "1b,cd"
since	integer (uint64)	no	How far back a first page reaches, in seconds (default 3600).	local-first-page: 3600local-resumed: 600

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/monitor?after=x0&limit=50&sources=mesh%2Cexecutor&for=1b&since=3600"

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	MonitorPage	Follow everything in one stream: 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.

MonitorPage

object

A page of the stream.

property	type	required	description
signals	array of MonitorSignal → MonitorSignal	yes	The signals, oldest first.
for_you	integer (uint)	yes	How many of them are for the reader.
suppressed	integer (uint64)	yes	How many records were read and folded away as noise.
sources	array of MonitorSourceState → MonitorSourceState	yes	Every source, read or not, with its reason.
cursor	string	yes	The cursor of the next page: ask with `after` set to it and nothing on this page comes back.
more	boolean	yes	Whether more signals wait after this page than its limit let through.

Used by monitor.stream

MonitorSeverity

"info" | "attention" | "action"

How much a signal asks of its reader.

infoSomething happened; nothing is asked.
attentionSomething failed or waits for someone: worth a look.
actionSomething waits for the reader: a review asked of them, a handover for them.

Used by MonitorSignal

MonitorSignal

object

One thing that happened, as one line a person or an agent can act on.

property	type	required	description
at	integer (uint64)	yes	When it happened, in Unix seconds, on the clock of whoever recorded it.
source	MonitorSource → MonitorSource	yes	Which record it comes from.
kind	string	yes	What happened, e.g. `session_joined`, `review_requested`, `merged`, `run_failed`.
severity	MonitorSeverity → MonitorSeverity	yes	How much it asks of the reader.
machine	string \| null	no	The machine it happened on, by its display name when the mesh knows it.
session	string \| null	no	The session that did it.
actor	string \| null	no	Who did it: a session's worker or client, the executor's actor, a GitHub login.
pr	integer \| null	no	The pull request it is about.
branch	string \| null	no	The branch it is about.
issue	string \| null	no	The issue it is about.
paths	array of string	no	The repository paths it is about.
summary	string	yes	What happened, in one line of at most 200 characters.
for_you	boolean	no	Whether it names the reader: a review asked of them, an answer to their request, a handover or a text that names them.
link	string \| null	no	Where to read more, when there is a page for it.

Used by MonitorPage

MonitorSource

"mesh" | "executor" | "github"

Where a signal comes from.

meshThe mesh journal: sessions on every linked machine (this checkout's board among them), their claims, handovers and reviews.
executorThe executor's trail: the pull-request lane's merges, refreshes, repairs, closures and failures.
githubGitHub: pull requests opened, merged and closed, and finished workflow runs.

Used by MonitorSignal MonitorSourceState

MonitorSourceHealth

"ok" | "absent" | "error" | "skipped"

Whether a source could be read, and what it contributed to the page.

okRead.
absentNot there to read: the mesh is not running, there is no trail, gh is missing.
errorThere, but reading it failed.
skippedNot asked for in sources.

Used by MonitorSourceState

MonitorSourceState

object

One source's standing on a page.

property	type	required	description
source	MonitorSource → MonitorSource	yes	The source.
state	MonitorSourceHealth → MonitorSourceHealth	yes	Whether it was read.
reason	string \| null	no	Why it was not, when it was not.
signals	integer (uint)	yes	How many of its signals are on this page.
suppressed	integer (uint64)	yes	How many of its records were read and folded away as noise.

Used by MonitorPage