HTTP API: web

What this repository exposes over HTTP, resolved from the producers that make it rather than from a register anybody maintains: the routes the executable answers itself, the documentation build, and every generated report that declared its own mount. The same resolution serves the router, renders the home page and composes a publication.

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.

web

GET /api/v1/web/surfaces web.surfaces

Every web surface, resolved

The web topology in route-precedence order, with each surface's mount, category, visibility, kind, producer, artifact, runtime feature and the provenance of every value a reader could be surprised by; and which ids are served, published and offered to a person. Answered from the resolution this process serves from, so it cannot disagree with what the router routes or what the home page lists.

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

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/web/surfaces"

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	SurfaceReport	Every web surface, resolved: 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.

Feature

"mcp" | "cockpit" | "ui"

A capability of the running process a surface needs in order to exist.

The registry describes the effective process, not the maximum one: a build or an invocation that answers no MCP has no MCP surface, and the home page cannot link to one. Stating the dependency as data is what keeps that automatic.

mcpThis process answers MCP over HTTP.
cockpitThis process serves the Cockpit.
uiThis process serves the UI: majordomus ui, the primary surface (ADR 0135).

Used by Surface

Mount

string

An absolute mount path, without a trailing slash.

Used by Surface

Provenance

one of 5 variants

Where a resolved value came from.

Kept for every field a consumer can be surprised by, so that web explain can answer "why is this mounted here?" without anybody reading the discovery code.

variant Read from the capability registry: the routes the executable already declares once.

source

"registry"

yes

variant Read from a producer's own declaration beside its output (surface.json).

path	string	yes	The declaration file, repository-relative.
source	"producer-declaration"	yes

variant Inferred from a file or directory being where the convention says it is.

path	string	yes	What was found, repository-relative.
source	"filesystem"	yes

variant Inferred from the site generator's own configuration.

path	string	yes	The configuration file, repository-relative.
source	"site-config"	yes

variant The model's documented default for a value nobody stated.

source

"default"

yes

Used by Surface

Surface

object

One resolved surface: everything a consumer needs, with the provenance of what it could be surprised by.

property	type	required	description
id	string	yes	Identity, unique across the topology; the selector `--only` and `--exclude` use it.
title	string	yes	One line: what a reader sees in a listing.
category	SurfaceCategory → SurfaceCategory	yes	What it is for, which is how a listing groups it.
visibility	SurfaceVisibility → SurfaceVisibility	yes	Whether a person is shown it.
kind	SurfaceKind → SurfaceKind	yes	How it answers.
mount	Mount → Mount	yes	Where it answers.
producer	string	yes	What produced it: a command, a module, or the generator that writes the directory.
feature	Feature \| null → Feature	no	The runtime capability it needs; absent when the process always has it.
artifact	string \| null	no	The generated directory, repository-relative, for a static surface.
index	string \| null	no	The file served for the mount itself, when the surface has one.
availability	SurfaceAvailability → SurfaceAvailability	yes	Where the surface's files go and who answers for it.
built_from	string \| null	no	The revision the artifact was built from, when its producer recorded one: what makes a stale build a finding rather than a surprise.
provenance	map of Provenance → Provenance	yes	Where each interesting value came from, by field name.

Used by SurfaceReport

SurfaceAvailability

"both" | "served-only" | "published-only"

Whether a surface is part of the static publication, served only while a process runs, or both.

bothServed by the running executable and published as files.
served-onlyAnswered by the running executable and never published: a route the process computes, or a build made for this server's own mount rather than for deployment.
published-onlyPublished as files; the running executable serves it from the same directory.

Used by Surface

SurfaceCategory

"interface" | "documentation" | "api" | "protocol" | "report"

What a surface is for, which is how a reader is shown it.

A category is the one piece of intent that a mount cannot carry: /openapi.json and /swagger sit beside each other and are a document and a viewer for it. Grouping is derived from this field and never from a list of paths kept somewhere else.

interfaceSomething a person opens and looks at: the home page, the Cockpit.
documentationProse and reference written for a person: the site, the Swagger UI.
apiA machine-readable surface of the capability registry.
protocolA wire protocol another program speaks.
reportGenerated evidence of a run: a test report, a benchmark report.

Used by Surface

SurfaceFinding

object

One thing wrong with a topology, said so a person can fix it without reading this file.

property	type	required	description
severity	SurfaceFindingSeverity → SurfaceFindingSeverity	yes	How much it matters.
rule	string	yes	The rule that produced it, stable enough to grep for.
surface	string	yes	The surface it is about.
message	string	yes	What is wrong.
remedy	string	yes	What to do about it.

Used by SurfaceReport

SurfaceFindingSeverity

"warning" | "error"

How much a finding matters.

warningWorth reading; serving is still coherent.
errorThe topology may not be served or published in this state.

Used by SurfaceFinding

SurfaceKind

"static-directory" | "native-route" | "redirect"

How a surface answers a request.

Only what this repository serves: a directory of generated files, a path the executable answers itself, and a redirect. A new kind is a new behaviour, never a new name for the same behaviour with different data.

static-directoryA generated directory, mounted under its prefix and served from disk.
native-routeA path the executable answers itself, from its own registry or handlers.
redirectA path that answers with a redirect to another one.

Used by Surface

SurfaceReport

object

The web surfaces of this repository, as the process that answers resolved them.

property	type	required	description
surfaces	array of Surface → Surface	yes	Every resolved surface, in route-precedence order: the order a router consults them in, so the first whose mount owns a path is the one that answers it.
served	array of string	yes	The ids a process answers for, in the same order. A surface published and not served is absent here.
published	array of string	yes	The ids a publication holds, in the same order.
public	array of string	yes	The ids offered to a person, which is what the home page lists.
findings	array of SurfaceFinding → SurfaceFinding	yes	What validation says about the topology as it stands. Empty is the healthy answer; a finding here is the same one `majordomus web validate` reports, with its remedy.

Used by web.surfaces

SurfaceVisibility

"public" | "internal"

Who a surface is offered to.

Two values and no more: a surface is either offered for a person to discover, or it is part of the topology without being advertised. Both are always in the machine-readable answer — hiding a served route from introspection would only hide it from the people maintaining it.

publicListed for a person: it appears on the home page.
internalServed and introspectable, not advertised: a machine speaks to it, or another surface links to it.

Used by Surface