HTTP API: dashboard

The Dashboard Suite as a projection of the canonical state: every card is one fact read out of an existing capability's answer, carrying the capability it asked, the input, the JSON pointer its value was read from, the Cockpit page that holds the evidence and the command that acts on it. No dashboard stores, counts or judges anything of its own (ADR 0088).

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.

dashboard

GET /api/v1/dashboard/overview dashboard.overview

The Overview: four questions

Is it healthy, what changed, what is broken, what needs action — each answered by cards read out of `health.report`, `release.version`, `plan.status`, `worktree.status`, `plan.next`, `continuity.state` and `peers.list` (this checkout's board), asked once each through the executor. Every card carries its source capability, input and RFC 6901 pointer, so asking the source the same question yields the same value; a source that cannot answer makes its cards `unknown`, never `ok`. Nothing here rebuilds canonical state or asks anything beyond this process and its checkout.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_dashboard_overview
$ dashboard overview

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/dashboard/overview"

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	DashboardOverview	The Overview: four questions: 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.

DashboardCard

object

One fact on a dashboard: a value read out of one capability's answer, the verdict the source gives it, where a reader drills in, and what acts on it.

use majordomus_cli::capability::builtin::dashboard::DashboardCard;
use serde_json::json;

let card: DashboardCard = serde_json::from_value(json!({
    "id": "health-status",
    "title": "Health",
    "value": "ok",
    "status": "ok",
    "detail": "the worst of 8 check(s)",
    "source": { "capability": "health.report", "input": {}, "pointer": "/status", "measure": "exact" },
    "route": "/cockpit/health",
})).unwrap();
// the value is the source's: reading the pointer out of its answer gives it back
assert_eq!(card.source.measure.read(&json!({ "status": "ok" }), &card.source.pointer), card.value);
assert!(card.action.is_none());

property	type	required	description
id	string	yes	A stable id, `[a-z][a-z0-9-]*`, unique across the dashboard.
title	string	yes	What the value is.
value	any	yes	The value, read out of the source's answer by the source's measure: a number, a string or a boolean, or `null` when the source holds none.
status	HealthStatus → HealthStatus	yes	The source's verdict on it; `unknown` when the source could not answer.
detail	string	yes	One line: what the value means, or why the source could not answer.
source	DashboardSource → DashboardSource	yes	Where the value came from.
route	string	yes	The Cockpit page a reader drills into for the evidence.
action	string \| null	no	The command that acts on it, when one does.

Used by DashboardQuestion

DashboardMeasure

"exact" | "count"

How a card's value is read out of its source's answer. Neither reading is arithmetic on the source's behalf.

use majordomus_cli::capability::builtin::dashboard::DashboardMeasure;
use serde_json::json;

let answer = json!({ "status": "warn", "tallies": { "ok": 6 }, "overlaps": [1, 2] });
// exact: the value at the pointer, null when there is none
assert_eq!(DashboardMeasure::Exact.read(&answer, "/status"), json!("warn"));
assert_eq!(DashboardMeasure::Exact.read(&answer, "/tallies/fail"), json!(null));
// count: a number as it stands, a list or map by its length, and an omitted one is none
assert_eq!(DashboardMeasure::Count.read(&answer, "/tallies/ok"), json!(6));
assert_eq!(DashboardMeasure::Count.read(&answer, "/overlaps"), json!(2));
assert_eq!(DashboardMeasure::Count.read(&answer, "/tallies/fail"), json!(0));

exactThe value at the pointer, exactly; null when the pointer resolves to nothing.
countThe number at the pointer, or the length of the list or map there; 0 when the source left it out, which is how the sources say an empty list or a zero tally.

Used by DashboardSource

DashboardOverview

object

The Overview: four questions, each answered by facts other capabilities hold.

use majordomus_cli::capability::builtin::dashboard::DashboardOverview;
use majordomus_cli::capability::builtin::HealthStatus;
use serde_json::json;

let o: DashboardOverview = serde_json::from_value(json!({ "status": "unknown", "questions": [] })).unwrap();
assert_eq!(o.status, HealthStatus::Unknown);

property	type	required	description
status	HealthStatus → HealthStatus	yes	The worst of the questions: `unknown` outranks `fail`, because an undecided fact is not a healthy one.
questions	array of DashboardQuestion → DashboardQuestion	yes	`healthy`, `changed`, `broken`, `action`, in that order.

Used by dashboard.overview

DashboardQuestion

object

One of the four questions the Overview answers, with the cards that answer it.

use majordomus_cli::capability::builtin::dashboard::DashboardQuestion;
use majordomus_cli::capability::builtin::HealthStatus;
use serde_json::json;

let q: DashboardQuestion = serde_json::from_value(json!({
    "id": "healthy", "title": "Is it healthy?", "status": "ok", "cards": [],
})).unwrap();
assert_eq!(q.status, HealthStatus::Ok);

property	type	required	description
id	string	yes	`healthy`, `changed`, `broken` or `action`.
title	string	yes	The question, as a reader asks it.
status	HealthStatus → HealthStatus	yes	The worst of its cards.
cards	array of DashboardCard → DashboardCard	yes	The facts that answer it, each read from a capability.

Used by DashboardOverview

DashboardSource

object

Where a card's value came from: the capability asked, the input it was asked with, and the pointer into its answer. Asking the capability the same question and reading the pointer with the same measure yields the card's value; that is the whole contract.

use majordomus_cli::capability::builtin::dashboard::{DashboardMeasure, DashboardSource};
use serde_json::json;

let s: DashboardSource = serde_json::from_value(json!({
    "capability": "health.report",
    "input": {},
    "pointer": "/status",
    "measure": "exact",
})).unwrap();
assert_eq!(s.measure, DashboardMeasure::Exact);
assert_eq!(s.measure.read(&json!({ "status": "ok" }), &s.pointer), json!("ok"));

property	type	required	description
capability	string	yes	The canonical id of the capability the value was read from.
input	any	yes	The input it was asked with, as its input schema takes it.
pointer	string	yes	An RFC 6901 JSON pointer into that capability's answer.
measure	DashboardMeasure → DashboardMeasure	yes	How the value is read at the pointer.

Used by DashboardCard