HTTP API: deploy

The deployments this repository declares, read from the canonical objects the index holds, and whether they would work — decided against the capability registry this process built and the workspace it sits in. Every operation is a read: a deployment is changed by the trusted command line and by CI, never over HTTP and never by an MCP client.

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.

deploy

GET /api/v1/deployment deploy.get

One deployment

One deployment by its identity, typed, with the repository-relative file it was read from.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_deployment

Query parameters

name	type	required	description	examples
id	string	yes	The deployment's `id`.	first-deployment: "majordomus"

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/deployment?id=majordomus"

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	DeploymentView	One deployment: 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/deployments deploy.list

Deployments

Every deployment the layer declares, typed: the application, the package and binary shipped, the address the process listens on, the routes a platform polls, the resources, the machine count, the region, the build inputs and the measured budgets. An object of the kind this executable cannot read is reported with the reason rather than skipped.

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

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

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	DeploymentList	Deployments: 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/deployments/check deploy.check

Would these deployments work

Every refusal the declared deployments earn locally: a health route no capability registers, a package or binary the workspace does not produce, a build input that does not resolve, more machines running than exist, a hosted process that would bind loopback. Each names the file, the key, the value observed and the correction. Nothing here contacts the provider.

query
behaviorally_verified
benchmark required
cache process (max_entries=2, ttl_seconds=5)
MCP tool majordomus_deploy_check

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/deployments/check"

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	DeploymentCheck	Would these deployments work: 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/deployments/observed deploy.observed

What was deployed, and where

Every deployment the forge recorded, to every environment it has one in — GitHub Pages among them — with the commit, the ref, who created it, how it ended, where it is served and the run that did it; every environment described by its newest deployment; and every release the forge published. Read from the record `majordomus served forge` wrote when it last asked the forge: nothing here reaches the network, and a checkout that has never asked answers `observed: false` with what to run.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_deployments_observed

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/deployments/observed"

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	ObservedDeployments	What was deployed, and where: 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.

Budgets

object

The measured figures this deployment is held to. Each is written by the run that measured it; an absent one has not been measured yet and is not a licence.

property	type	required	description
image_bytes	Positive \| null → Positive	no	Largest accepted compressed image size.
binary_bytes	Positive \| null → Positive	no	Largest accepted stripped binary size.
build_context_bytes	Positive \| null → Positive	no	Largest accepted build context.
cold_start_ms	Positive \| null → Positive	no	Longest accepted time from a stopped machine to a served response.
resident_memory_mb	Positive \| null → Positive	no	Largest accepted resident set under load.
blocking_check_ms	Positive \| null → Positive	no	Longest accepted time for one liveness or readiness check.
request_p99_ms	Positive \| null → Positive	no	Longest accepted p99 for a served request.

Used by DeploymentView

Build

object

What is shipped and what it is built from.

property	type	required	description
package	string	yes	The Cargo package that is built.
binary	string	yes	The binary target the image runs.
profile	string	yes	The Cargo profile the image is built under.
inputs	array of string	yes	The repository-relative paths the build context carries, and the only ones.
site	string \| null	no	The directory the canonical site pipeline writes; absent means the image serves no site.

Used by DeploymentView

CpuKind

"shared" | "performance"

What a machine's CPU is.

sharedA fraction of a core: the cheap profile.
performanceA dedicated one.

Used by Resources

DeploymentCheck

object

Whether the deployments this repository declares would work, decided locally: against the capability registry this process built and the workspace it sits in.

property	type	required	description
ok	boolean	yes	True when no deployment earned a refusal.
decided	integer (uint)	yes	How many deployments were decided.
refusals	array of Refusal → Refusal	yes	Every refusal, in the order the objects and their keys appear.

Used by deploy.check

DeploymentList

object

Every deployment the layer declares.

property	type	required	description
count	integer (uint)	yes	How many.
deployments	array of DeploymentView → DeploymentView	yes	Each, in identity order.
unreadable	array of Refusal → Refusal	no	Objects of the deployment kind this executable could not read, with why. A malformed object is reported here rather than hidden by being skipped.

Used by deploy.list

DeploymentStatus

"declared" | "active" | "retired"

Where a deployment stands.

Status is the right name inside this module; the schema component namespace is flat, and distribution::Status answers a different question, so each says which it is.

declaredThe object exists and nothing is deployed from it yet.
activeIt is deployed.
retiredIt was, and the object is kept for the record.

Used by DeploymentView

DeploymentView

object

One deployment as this process reads it, with where it came from.

property	type	required	description
file	string	yes	The repository-relative file the object lives in.
schema	string	yes	The format version; a version this executable does not read is refused.
kind	string	yes	Always `deployment`.
id	string	yes	The identity within the repository.
title	string	yes	One line naming it.
description	string \| null	no	One line: what it serves and to whom.
status	DeploymentStatus \| null → DeploymentStatus	no	Where it stands.
application	string	yes	The application's name: what the deployment is known by in a listing.
build	Build → Build	yes	What is shipped and what it is built from.
listen	Listen → Listen	yes	The address the process listens on.
health	HealthRoutes → HealthRoutes	yes	The routes a platform polls.
resources	Resources → Resources	yes	What one machine is granted.
machines	Machines → Machines	yes	How many machines run.
region	string	yes	The region they run in.
budgets	Budgets → Budgets	no	The measured figures it is held to.
created_at	string \| null	no	When the object was written.
updated_at	string \| null	no	When it was last changed.

Used by deploy.get DeploymentList

EnvironmentSummary

object

One environment, as its deployments describe it.

property	type	required	description
name	string	yes	The environment.
deployments	integer (uint)	yes	How many of the observed deployments went to it.
state	string	yes	The state of its newest deployment.
sha	string	yes	The commit its newest deployment put there.
deployed_at	string	yes	When that was.
url	string \| null	no	Where it is served, when its newest deployment says.
activity_url	string	yes	The environment's activity on the forge.

Used by ObservedDeployments

HealthRoutes

object

The routes a platform polls, and how often.

property	type	required	description
liveness	Route → Route	yes	Is this process alive.
readiness	Route → Route	yes	Can this process serve traffic.
grace_seconds	integer \| null	no	How long the platform waits before the first check counts.
interval_seconds	Positive \| null → Positive	no	How often the platform polls liveness.
timeout_seconds	Positive \| null → Positive	no	How long one check may take before it counts as failed.

Used by DeploymentView

Interface

"loopback" | "all"

Which interface a process listens on.

loopbackReachable from this host alone: the local default, and what every local invocation keeps.
allEvery interface. A hosted process needs it and a local one never does; stating it is the intent that replaces suppressing the bind warning.

Used by Listen

Listen

object

The address the process listens on.

property	type	required	description
port	Port → Port	yes	The port, stated once for the process and the image.
interface	Interface → Interface	yes	Which interface.

Used by DeploymentView

Machines

object

How many machines run, and whether the platform may stop them.

property	type	required	description
count	Positive → Positive	yes	How many machines the application has.
min_running	integer (uint32)	yes	How many stay running when idle.
autostart	boolean	yes	Whether a request to a stopped machine starts it.
autostop	boolean	yes	Whether an idle machine is stopped.

Used by DeploymentView

ObservedDeployment

object

One deployment the forge recorded.

property	type	required	description
id	string	yes	The forge's identity of the deployment.
environment	string	yes	The environment it went to, in the forge's words (`github-pages`, `production`, ...).
sha	string	yes	The commit that was deployed.
git_ref	string \| null	no	The ref it was deployed from, when the forge still names one.
created_at	string	yes	When it was created, RFC 3339.
creator	string \| null	no	Who or what created it.
state	string	yes	How it ended, lower case as the forge states it (`success`, `failure`, `in_progress`, ...); `unknown` when the forge reported no status at all.
environment_url	string \| null	no	Where the environment is served, when the deployment says.
log_url	string \| null	no	The run that performed it, when the deployment says.

Used by ObservedDeployments

ObservedDeployments

object

deploy.observed: what was deployed where, or that nothing has been observed here.

property	type	required	description
observed	boolean	yes	Whether this checkout holds an observation at all.
reason	string \| null	no	Why not, and what to run, when it holds none or cannot read it.
repository	string \| null	no	`owner/name`, when observed.
repository_url	string \| null	no	The repository's address on the forge, when observed.
observed_at	string \| null	no	When the forge was asked, when observed.
environments	array of EnvironmentSummary → EnvironmentSummary	yes	Every environment something was deployed to, by name.
deployments	array of ObservedDeployment → ObservedDeployment	yes	The observed deployments, newest first.
releases	array of ObservedRelease → ObservedRelease	yes	The observed releases, newest first.

Used by deploy.observed

ObservedRelease

object

One release the forge published.

property	type	required	description
tag	string	yes	The tag.
name	string \| null	no	The release's title, when it has one.
published_at	string \| null	no	When it was published; absent for a draft.
url	string	yes	Its page on the forge.
prerelease	boolean	yes	Whether the forge marks it a pre-release.
draft	boolean	yes	Whether it is still a draft.

Used by ObservedDeployments

Port

integer (uint16)

A TCP port a deployed process may bind. Privileged ports are not among them: the process runs as a non-root user and could not bind one.

Used by Listen

Positive

integer (uint32)

A count that is at least one: memory in megabytes, CPUs, machines. Zero is refused wherever zero would mean "a deployment that cannot run".

Used by Budgets HealthRoutes Machines Resources

Refusal

object

Why a deployment object is refused: what was read, where, and what to do about it.

property	type	required	description
file	string	yes	The repository-relative file the value came from.
key	string	yes	The key path within it, as the contract names it.
found	string	yes	The value observed, rendered as it was read.
problem	string	yes	What is wrong with it, in one line.
correction	string	yes	What to do instead.

Used by DeploymentCheck DeploymentList

Resources

object

What one machine is granted.

property	type	required	description
cpu_kind	CpuKind → CpuKind	yes	Shared or dedicated.
cpus	Positive → Positive	yes	How many CPUs one machine has.
memory_mb	Positive → Positive	yes	Memory per machine, in megabytes.

Used by DeploymentView

Route

string

A route a platform polls: an absolute path on this service, never a URL. The host is the deployment's to know and not the object's to state.

Used by HealthRoutes