HTTP API: graph

The graphs derived from the registry and the index: the executable's own capability registry, the shape of the layer, the rule dependencies, the decisions and what they put in force, and the use cases and what they exercise. Canonical nodes and edges; a rendering library is a consumer, never the shape.

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.

graph

GET /api/v1/graph graph.get

Derive one graph

One graph by id: its nodes and edges with the vocabularies that say what each kind means, the file every node was derived from, and whether the result is acyclic. Deterministic for a given tree and executable.

query
behaviorally_verified
benchmark required
cache process (max_entries=16)
MCP tool majordomus_graph

Query parameters

name	type	required	description	examples
id	string	yes	The graph's id, as `graph.list` gives it (`registry`, `layer`, `rules`, `adrs`, `use-cases`).	adrs: "adrs"composed: "composed"layer: "layer"product: "product"registry: "registry"rules: "rules"use-cases: "use-cases"why: "why"

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/graph?id=adrs"

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	Graph	Derive one graph: 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/graphs graph.list

List graphs

Every graph this executable derives: its id, what it shows, and what it is derived from.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_graphs
MCP resource {"name": "graphs", "uri": "majordomus://graphs"}

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/graphs"

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	GraphList	List graphs: 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.

Edge

object

One directed edge. Both ends are node ids of the same graph; a derivation that cannot resolve an end adds an external node rather than a dangling edge.

property	type	required	description
source	string	yes	The node the edge leaves.
target	string	yes	The node the edge enters.
kind	string	yes	One of the graph's declared edge kinds.

Used by Graph

Fact

boolean | integer (int64) | string | array of string

One fact a node carries from its object's front matter, in the shapes a node can hold.

Used by Node

Graph

object

A derived graph: what it is, where it came from, what its vocabularies mean, and the nodes and edges themselves.

property	type	required	description
id	string	yes	The identity, `[a-z][a-z0-9-]*`; the last segment of its route.
title	string	yes	The short name.
description	string	yes	One paragraph: what a reader learns from it.
source	string	yes	What it was derived from, in the repository's own words.
node_kinds	map of string	yes	Node kind to what that kind means.
edge_kinds	map of string	yes	Edge kind to what that edge asserts.
nodes	array of Node → Node	yes	Sorted by id.
edges	array of Edge → Edge	yes	Sorted.
metadata	GraphMetadata → GraphMetadata	yes	Counts and invariants.

Used by graph.get

GraphInfo

object

One graph the executable can derive: what it is, without deriving it.

property	type	required	description
id	string	yes	The identity.
title	string	yes	The short name.
description	string	yes	One paragraph.
source	string	yes	What it is derived from.

Used by GraphList

GraphList

object

Every graph this executable derives.

property	type	required	description
count	integer (uint)	yes	How many.
graphs	array of GraphInfo → GraphInfo	yes	Each, described but not derived.

Used by graph.list

GraphMetadata

object

What a reader needs to know about the graph as a whole before drawing it.

property	type	required	description
nodes	integer (uint)	yes	How many nodes.
edges	integer (uint)	yes	How many edges.
acyclic	boolean	yes	Whether the edges form a directed acyclic graph. Derived, never declared: a graph whose contract is a DAG and whose answer here is `false` is a defect in the data.
truncated	boolean	yes	True when the derivation stopped at `MAX_NODES` and the graph is a prefix of what the repository holds.

Used by Graph

Node

object

One node. id is unique within the graph; kind is what the graph's node_kinds declares it to be; route is where the Cockpit shows the thing itself, when it shows it anywhere.

property	type	required	description
id	string	yes	Unique within the graph.
kind	string	yes	One of the graph's declared node kinds.
label	string	yes	The short label a renderer draws.
summary	string \| null	no	One line about the thing, when the source holds one.
route	string \| null	no	Where the Cockpit shows this thing, when it shows it.
source	string \| null	no	The repository-relative file the node was derived from, when one file owns it.
status	string \| null	no	A status word the graph's own vocabulary defines (`accepted`, `active`, `query`).
external	boolean	no	True when the node stands for something the graph names but does not hold: a reference that resolves to nothing in this repository.
facts	map of Fact → Fact	no	What the object's own kind declares about it, as its schema validated it: the fields of its front matter that are facts about the thing rather than the document itself. A rule carries its class and its statement, a skill its inputs and outputs, a decision its date — the vocabulary that makes each kind worth having, rather than the four fields every kind happens to share.

Used by Graph