HTTP API: board

The documents the delivery board reads, derived from the plan, the roadmap, the intents, the recorded pull request queue and the release currency, with the lanes share/board.yaml declares once. Every open milestone is in a lane or the snapshot refuses, naming it.

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.

board

GET /api/v1/board/snapshot board.snapshot

The delivery board's documents

Every document of the delivery board by id: meta (the commit, the lanes, the issue counts, the release), milestones in roadmap order, intents, the pull request queue from the last recorded observation, and the open issues of each lane as issues-<lane>, split into issues-<lane>-2 and onwards so that no document serializes past 250000 bytes. The digest is a SHA-256 over the canonical JSON of the documents with meta.syncedAt and meta.syncedBy left out, so equal state is an equal digest. A milestone that is not DONE and is in no lane of share/board.yaml is refused by name, never filed under other. An unobserved queue is said in prs.unavailable and the diagnostics, never refused. Mesh seats, live work, CI runners and blockers are the sync step's and are not here. Reads only; nothing is cached.

query
experimental
benchmark waived: repository_declaration
cache disabled
MCP tool majordomus_board_snapshot
$ board snapshot

Query parameters

name	type	required	description	examples
by	string	no	Who takes the snapshot, as `meta.syncedBy` names it; `board.snapshot` when absent. Left out of the digest.	named: "a mesh session"

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/board/snapshot?by=a%20mesh%20session"

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	BoardSnapshot	The delivery board's documents: 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.

BoardSnapshot

object

The answer of board.snapshot: every document of the board by id, and the digest that says whether two snapshots describe the same state.

property	type	required	description
digest	string	yes	`sha256:<hex>` over the canonical JSON of the documents, `meta.syncedAt` and `meta.syncedBy` left out: equal state, equal digest.
master_sha	string	yes	The commit described, empty when the checkout has none.
master_committed_at	string	yes	Its committer time, RFC 3339.
master_ref	string	yes	The ref it was read from: `refs/remotes/origin/master`, else `HEAD`.
document_limit	integer (uint)	yes	The bound every document is under, in bytes of compact JSON.
sizes	map of integer (uint)	yes	Each document's compact size, in bytes, by id.
documents	object	yes	The documents, by id: `meta`, `milestones`, `intents`, `prs`, and `issues-<lane>` (then `issues-<lane>-2`, ...) for each lane with open work.
diagnostics	array of string	no	What could not be read, in words: an unobserved pull request queue, a lane naming a milestone the plan lacks. Empty is the ordinary case.

Used by board.snapshot