HTTP API: distribution

How this project is packaged, published and installed: the platforms a release builds, the artifact names the one naming function derives, the installer's canonical command, the releases that were published, and what this build itself is. Every answer comes from share/distribution.yaml and the release records; no surface here states a fact of its own.

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.

distribution

GET /api/v1/distribution distribution.model

The distribution model

The one-line install command, where an installation goes, and every declared target with the artifact name it derives. This is what the installation page, the landing page's install block and the cockpit's install card render; none of them holds a platform list of its own.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_distribution
$ distribution show

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

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	DistributionReport	The distribution model: 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/distribution/artifact distribution.artifact

The artifact of a target

The archive name a target and a tag derive, the directory it unpacks into, and where a release publishes it. The one naming function answers; the release pipeline asks it rather than composing a name in a workflow file.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_artifact
$ distribution artifact

Query parameters

name	type	required	description	examples
target	string	yes	A target's id or its Rust target triple.	first-published-target: "aarch64-apple-darwin"
tag	string	yes	The tag, `v` and a version. `{tag}` asks for the name with the placeholder left in.	first-published-target: "v0.0.0"

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/distribution/artifact?target=aarch64-apple-darwin&tag=v0.0.0"

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	ReleaseArtifactView	The artifact of a target: 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/distribution/build distribution.build

This build

What this executable is: the version of the crate it was built from, the Rust target triple, the profile, and the commit — all compiled in at build time, so an installed binary answers without a repository, a toolchain or git.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_build
$ distribution build

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/distribution/build"

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	BuildReport	This build: 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/distribution/releases distribution.releases

Published releases

Every release this repository recorded, newest first, and the one an unpinned installation resolves to: the highest version among the stable, unwithdrawn records. The pointer is derived here and never authored anywhere.

query
behaviorally_verified
benchmark required
cache generation (max_entries=1)
MCP tool majordomus_releases
$ distribution releases

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/distribution/releases"

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	ReleasesReport	Published releases: 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/distribution/status distribution.status

Whether the published installation works

Whether a machine that has never seen this project can install it right now with the advertised one-line command, and when it cannot, which link in the chain is missing and what changes it. Derived from the distribution model and the release records alone: it reaches no network, so it is as fast as any other local query and answers offline. The served bytes are proved by the release pipeline's smoke phase, not guessed at here.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_install_status
$ distribution status

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/distribution/status"

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	InstallabilityReport	Whether the published installation works: 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.

Arch

"x86_64" | "aarch64"

A processor architecture.

x86_6464-bit x86, detected as x86_64 or amd64.
aarch6464-bit ARM, detected as aarch64 or arm64.

Used by TargetView

BuildReport

object

What this executable is: enough to tell two builds apart without asking a repository.

property	type	required	description
version	string	yes	The version of the crate this executable was built from.
target	string	yes	The Rust target triple it was built for; the model names a target by the same string.
profile	string	yes	The cargo profile.
commit	string	yes	The commit, or `unknown` when it was built outside a work tree.
distribution_target	string \| null	no	The target of the model this build matches, when the model declares one for the triple.

Used by distribution.build

Channel

"stable" | "prerelease"

Which releases an unpinned installation may resolve to.

stableResolved by latest.
prereleasePublished, addressable by its exact tag, never resolved by default.

Used by ReleaseView

CheckState

"ok" | "failed" | "unknown"

The state of one check in the installability report. Three states and no more: a check either holds, does not, or could not be made from what this process can see.

okThe check holds.
failedThe check does not hold, and the public installation is affected.
unknownThe check could not be made here; it says nothing either way.

Used by InstallCheck

DistributionReport

object

The distribution, as a person or a script asks for it.

property	type	required	description
binary	string	yes	The command a person types after installing.
repository	string	yes	`owner/name`, the only host release assets come from.
installer_url	string	yes	The installer's canonical URL.
install_command	string	yes	The one-line install command, composed from its parts.
install_and_init_command	string	yes	The same, initialising the repository afterwards.
next_command	string	yes	What a person runs next.
checksum	string	yes	The digest algorithm the installer verifies.
install_dir	string	yes	Where the launchers go by default.
prefix	string	yes	Where the versioned trees go by default.
latest_url	string	yes	Where the stable release metadata is published.
supported	integer (uint)	yes	How many targets a release builds.
targets	array of TargetView → TargetView	yes	Every declared target, in the model's order.

Used by distribution.model

InstallCheck

object

One check: what was asked, what was seen, and — when it does not hold — why, and the command that changes it. The cause and next fields exist so that a report is actionable without a second document; a check that fails without naming its remedy is a diagnostic nobody can act on.

property	type	required	description
id	string	yes	A short stable name: `model`, `version`, `targets`, `release`, `artifacts`, `metadata`.
state	CheckState → CheckState	yes	Whether it holds.
observed	string	yes	What was observed, in one line.
cause	string \| null	no	Why it does not hold. Absent when it does.
next	string \| null	no	The command or action that would change it. Absent when there is nothing to do.

Used by InstallabilityReport

InstallabilityReport

object

Whether the advertised one-line installation works right now, and if not, what is missing.

This answers the operator's actual question — can a machine that has never seen this project install it with the published command? — from local state alone. It performs no network access: a repository can be offline and this still answers, because everything it needs is the distribution model and the release records the repository itself carries. What it cannot see it reports as unknown rather than guessing; the public half of the question is answered by the release workflow's smoke phase, which installs from the published URL on every native runner and is the only thing that proves the public path.

property	type	required	description
installable	boolean	yes	True when every check holds: a stable release is recorded and complete.
summary	string	yes	One line for a person: what the state is, in the project's own terms.
local_version	string	yes	The version this tree would release.
stable_tag	string \| null	no	The tag an unpinned installation resolves to, when a stable release is recorded.
required_targets	integer (uint)	yes	How many targets a release must publish for that release to be complete.
published_artifacts	integer (uint)	yes	How many of them the stable release actually publishes.
install_command	string	yes	The command a person would run, whether or not it currently works.
installer_url	string	yes	Where the installer is served.
latest_url	string	yes	Where the stable pointer is served.
checks	array of InstallCheck → InstallCheck	yes	Every check, in the order they are worth reading.

Used by distribution.status

Libc

"gnu" | "musl"

The C library a Linux artifact is linked against.

gnuGNU libc: the ordinary distributions.
muslmusl: Alpine, and any statically linked artifact.

Used by TargetView

Os

"macos" | "linux" | "windows"

An operating system a target runs on.

macosApple's, detected as Darwin.
linuxLinux, detected as Linux, and the only one where the C library matters.
windowsWindows; representable, and not built today.

Used by TargetView

ReleaseArtifactView

object

The artifact a target and a tag name, and the directory it unpacks into.

property	type	required	description
target	string	yes	The target's id in the model.
rust_target	string	yes	The Rust target triple.
tag	string	yes	The tag the name was derived for.
name	string	yes	The archive's file name.
root	string	yes	The directory the archive unpacks into.
url	string	yes	Where a release publishes it, when the tag is a real one.

Used by distribution.artifact

ReleaseView

object

One release, as every projection shows it.

property	type	required	description
tag	string	yes	The git tag.
version	string	yes	The semantic version.
channel	Channel → Channel	yes	Whether an unpinned installation may resolve it.
published_at	string	yes	When it was published, UTC.
commit	string	yes	The commit it was built from.
yanked	boolean	yes	True when it has been withdrawn.
artifacts	integer (uint)	yes	How many artifacts it published.
metadata_url	string	yes	Where its public metadata is served.

Used by ReleasesReport

ReleasesReport

object

The releases this repository recorded, and the one an unpinned installation resolves to.

property	type	required	description
count	integer (uint)	yes	How many records there are.
latest	ReleaseView \| null → ReleaseView	no	The release an unpinned installation resolves to, when there is one.
releases	array of ReleaseView → ReleaseView	yes	Every record, newest first.

Used by distribution.releases

TargetStatus

"supported" | "experimental" | "unavailable"

What the project promises about a target.

See crate::deploy::Status: both are Status in their own module and neither is in the one component namespace the schema document has.

supportedBuilt by every release, offered by the installer, listed as supported. A release that is missing this artifact is not published.
experimentalBuilt and offered, and documented as not yet proven.
unavailableDocumented, never built, refused by the installer with its recorded reason.

Used by TargetView

TargetView

object

One target, as every projection shows it: what it is, what it is called in prose, and the artifact name the naming function derives for a tag yet to be chosen.

property	type	required	description
id	string	yes	The target's id in the model.
title	string	yes	How it is written in prose: `Linux x86_64 musl`.
os	Os → Os	yes	The operating system.
arch	Arch → Arch	yes	The architecture.
libc	Libc \| null → Libc	no	The C library, on Linux.
rust_target	string	yes	The Rust target triple.
status	TargetStatus → TargetStatus	yes	What the project promises about it.
reason	string \| null	no	Why, when it is not built.
artifact	string	yes	The artifact name, with `{tag}` where a release's tag goes.

Used by DistributionReport