HTTP API: artifacts

What `majordomus generate` writes: every document with the encodings it is committed in — JSON for a program, YAML beside it, Markdown for a reader — each with its schema, its source and its hash, reconciled with the working tree. The declaration is the generator's own manifest; nothing here keeps a list.

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.

artifacts

GET /api/v1/artifacts artifacts.list

List the generated artifacts

The manifest `majordomus generate` commits as docs/generated/artifacts.json, reconciled with the working tree: every document with the encodings it is written in, and every file with its format, schema, source, size, hash and whether the file on disk still matches. Optionally narrowed to one document or one encoding. Reads only; `majordomus generate` writes and `majordomus generate --check` is the byte-for-byte verdict.

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

Query parameters

name	type	required	description	examples
document	string	no	Only the artifacts of this document (`registry`, `cli`, `openapi`, ...).
format	ArtifactFormat \| null	no	Only the artifacts written in this encoding.	one-encoding: "yaml"

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/artifacts?format=yaml"

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	ArtifactReport	List the generated artifacts: 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.

ArtifactFormat

"json" | "yaml" | "markdown" | "text"

The encoding one generated artifact is written in.

jsonA JSON document: pretty-printed, one trailing newline, provenance as members.
yamlThe same document in the layer's YAML, provenance as a comment banner.
markdownMarkdown for a reader, provenance as an HTML comment.
textLine-oriented text another program reads: the shell tool's allow-lists, provenance as # comments.

Used by artifacts.list ArtifactView DocumentView

ArtifactReport

object

The answer of artifacts.list.

property	type	required	description
manifest	string	yes	The manifest this was read from, repository-relative.
present	boolean	yes	Whether the manifest is committed in this repository at all. A repository that has never run `majordomus generate` has no generated tree, which is a fact about it and not a failure of this call: every list below is then empty and every tally zero.
schema	string	yes	The schema the manifest carries, empty when there is none to read.
documents	array of DocumentView → DocumentView	yes	The documents, in the manifest's order.
artifacts	array of ArtifactView → ArtifactView	yes	The files, in the manifest's order, after any filter.
tallies	ArtifactTallies → ArtifactTallies	yes	The counts.
verdict	ArtifactVerdict → ArtifactVerdict	yes	Where the tree stands as a whole, decided from every tally.
regenerate	string	yes	The command that rewrites every one of them.
verify	string	yes	The command that decides staleness byte for byte, which is stronger than the hash.

Used by artifacts.list

ArtifactState

"current" | "stale" | "missing" | "present"

Where one generated file stands against the tree it is committed in.

currentThe file is there and its bytes hash to what the manifest recorded.
staleThe file is there and its bytes differ: it was edited, or the generator moved on.
missingThe manifest names it and the tree does not have it.
presentThe file is there and the manifest records no hash for it: the manifest's own encodings, which cannot hash themselves. generate --check compares them.

Used by ArtifactView

ArtifactTallies

object

How many of each, so a caller needs no arithmetic of its own.

property	type	required	description
documents	integer (uint)	yes	Documents in the manifest.
artifacts	integer (uint)	yes	Files in the manifest, after any filter.
current	integer (uint)	yes	Hashes that match.
stale	integer (uint)	yes	Hashes that do not.
missing	integer (uint)	yes	Files the manifest names and the tree lacks.
present	integer (uint)	yes	Files the manifest records no hash for.

Used by ArtifactReport

ArtifactVerdict

"current" | "unverified" | "stale" | "missing" | "not_generated"

Where the generated tree stands as a whole: the one verdict every surface renders, decided here so that no page decides it again from a subset of the tallies.

use majordomus_cli::capability::builtin::artifacts::ArtifactVerdict;
let v: ArtifactVerdict = serde_json::from_str("\"unverified\"").unwrap();
assert_eq!(v, ArtifactVerdict::Unverified);
assert!(ArtifactVerdict::Current < ArtifactVerdict::Unverified);

currentEvery file is there and hashes to what the manifest recorded.
unverifiedEvery file is there, none is stale, and some carry no recorded hash: their bytes were not compared here, so the tree is not known to be current. majordomus generate --check is what decides them.
staleA file differs from what the manifest recorded.
missingA file the manifest names is not in the tree.
not_generatedNo manifest is committed: the repository has never run majordomus generate.

Used by ArtifactReport

ArtifactView

object

One generated file, as the manifest declares it and as the tree has it.

property	type	required	description
path	string	yes	Repository-relative path.
document	string	yes	The document it projects.
format	ArtifactFormat → ArtifactFormat	yes	The encoding.
schema	string \| null	no	The JSON Schema its content satisfies, when it declares one.
source	string	yes	One line: what it was derived from.
bytes	integer \| null	no	The size the manifest recorded.
sha256	string \| null	no	The hash the manifest recorded.
state	ArtifactState → ArtifactState	yes	Where the file stands against it.

Used by ArtifactReport

DocumentView

object

One document, and the encodings it is committed in.

property	type	required	description
id	string	yes	The document id, shared by every encoding of it.
schema	string \| null	no	The schema id its structured encodings carry.
source	string	yes	One line: what it was derived from.
formats	array of ArtifactFormat → ArtifactFormat	yes	The encodings, in the manifest's order.

Used by ArtifactReport