HTTP API: repository

The repository this process serves: its layer, its git state, the state of the index built from it, and its scope: what a worker reads of it and what it never reads.

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.

repository

The repository this process serves: its layer, its git state, the state of the index built from it, and its scope: what a worker reads of it and what it never reads.

GET /api/v1/repository repository.info

Repository and index state

The repository root, layer sections, git state, discovery mode, kinds present, every diagnostic, and the capability registry counted.

query
behaviorally_verified
benchmark required
cache generation (max_entries=1)
MCP tool majordomus_repository
MCP resource {"name": "repository", "uri": "majordomus://repository"}

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

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	RepositoryReport	Repository and index state: 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/scope repository.scope

The repository scope

The scope declaration as read, where it came from (the repository's own or the distribution's default), and every tracked file tallied against it: how many are in, how many are out for each reason, and which.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_scope
MCP resource {"name": "scope", "uri": "majordomus://scope"}
$ scope

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

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	ScopeReport	The repository scope: 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/scope/classify repository.scope_classify

Judge a path against the scope

Whether a repository-relative path is in or out of the scope, the reason when it is out, and the pattern or limit that decided; an existing file is judged by name, then size, then content.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_scope_classify

Query parameters

name	type	required	description	examples
path	string	yes	Repository-relative, forward slashes; `./` is stripped. An absolute path or a `..` segment is an invalid input.	first-object: ".ai/repo/adrs/0001-rust-cli-and-stdio-mcp.md"layer-file: ".ai/manifest.yaml"local-half: ".ai/local/state/current.yaml"secret: "config/.env"undeclared: "node_modules/left-pad/index.js"

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/scope/classify?path=.ai%2Frepo%2Fadrs%2F0001-rust-cli-and-stdio-mcp.md"

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	Classification	Judge a path against the scope: 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.

Classification

object

One path, judged.

property	type	required	description
path	string	yes	The path, repository-relative, as judged.
verdict	Verdict → Verdict	yes	In or out.
reason	Reason \| null → Reason	no	Why it is out; absent when it is in.
rule	string \| null	no	The pattern or limit that decided: the `in` pathspec, the `out` pattern, `binary`, `max_bytes` or `fixtures.max_bytes`; absent for `undeclared`.
exists	boolean	yes	Whether the path exists in the work tree; a path that does not is judged by name.
directory	boolean	yes	Whether the path is a directory; a directory is in when something beneath it can be.
bytes	integer \| null	no	The size, when the path is an existing file.

Used by repository.scope_classify

Declaration

object

scope.yaml, typed. Unknown keys are refused by the type and by the scope schema.

property	type	required	description
version	integer (uint64)	yes	The format version; only `SCOPE_VERSION` is read.
in	array of string	yes	The allow-list: pathspecs anchored at the repository root.
out	Out → Out	yes	What is never read; wins over `in`.

Used by ScopeReport

Fixtures

object

The fixtures category: where fixtures live and how large one may be.

property	type	required	description
paths	array of string	no	Pathspecs anchored at the repository root.
names	array of string	no	Patterns matched against the file name alone.
max_bytes	integer (uint64)	yes	A fixture over this many bytes is out.

Used by Out

GitInfo

object

What git said about the repository.

property	type	required	description
toplevel	string	yes	Absolute path of the work tree top level.
head	string \| null	no	Full commit id of HEAD, or `None` in an unborn repository.
branch	string \| null	no	Branch name, or `None` when detached or unborn.
working_tree	string	yes	`clean` or `dirty`, from `git status --porcelain`.

Used by GitState

GitState

one of 2 variants

What git says about the repository, or why it could not be asked.

variant git answered; the facts follow.

state

"available"

yes

variant git could not be asked, or the root is not a work tree; the reason says which.

reason	string	yes	What `git` said, or why it could not be run.
state	"unavailable"	yes

Used by RepositoryInfo

Origin

"repository" | "distribution"

Where the declaration was read from.

repositoryThe repository's own, named by the manifest's scope section.
distributionThe distribution's default, because the repository declares none.

Used by RepositoryInfo ScopeReport

Out

object

The out: mapping: every category optional, each the reason a path is out.

property	type	required	description
paths	array of string	no	Never read, by path: version control, the local half, dependencies, build outputs.
binary	boolean	no	Content that is not text (a NUL byte in the first window) is out, whatever the name says.
max_bytes	integer \| null	no	A file over this many bytes is out, whatever it is.
archive	Category \| null → Category	no	Archives.
image	Category \| null → Category	no	Images.
video	Category \| null → Category	no	Video.
pdf	Category \| null → Category	no	PDF documents.
database_dump	Category \| null → Category	no	Database dumps.
generated	Category \| null → Category	no	Generated assets: changed by changing the source and regenerating.
secret	Category \| null → Category	no	Secrets: never read, never served, never quoted; a tracked one is reported.
fixtures	Fixtures \| null → Fixtures	no	Fixtures are read up to a size; over it they are data, not context.

Used by Declaration

OutFile

object

One tracked file that is out.

property	type	required	description
path	string	yes	Repository-relative.
reason	Reason → Reason	yes	Why.
rule	string \| null	no	The rule that decided; absent for `undeclared`.

Used by Tally

Reason

Why a path is out. The order is the order the rules decide in.

pathNamed under out.paths.
secretA secret.
generatedA generated asset.
archiveAn archive.
imageAn image.
videoVideo.
pdfA PDF document.
database_dumpA database dump.
undeclaredMatches no in pathspec.
fixture_over_limitA fixture over out.fixtures.max_bytes.
over_limitOver out.max_bytes.
binaryContent with a NUL byte in its first SNIFF_BYTES: not text.

Used by Classification OutFile

RepositoryInfo

object

What the index knows about the repository it was built from.

property	type	required	description
root	string	yes	The repository root, absolute.
layer_schema	string	yes	The manifest's `schema`, `ai-repository/v1`.
sections	map of string	yes	Manifest section name to repository-relative path.
git	GitState → GitState	yes	What `git` said, or why it could not be asked.
discovery	string	yes	`vcs` or `filesystem`.
source_classes	array of array of any	yes	Source class id to kind, in declared order.
kind_sources	array of string	yes	The kinds files the reader was configured from: the distribution's, then the repository's own when it has one.
scope_origin	Origin → Origin	yes	Where the scope was read from: `repository` or `distribution`.
scope_path	string	yes	The scope file: repository-relative for the repository's own, the share path for the distribution's default.
observed	RepositoryObservations → RepositoryObservations	no	When the index and the git state it carries were read. Defaults to empty so that a record written before the freshness contract still reads.

Used by RepositoryReport

RepositoryObservations

object

The two pictures a process takes of the repository, each with when it was taken.

A picture without a window is never stale, and its window is not serialized.

use std::time::{Duration, UNIX_EPOCH};
use majordomus_cli::index::{AnswerObservation, RepositoryObservations};
let now = RepositoryObservations {
    index: AnswerObservation::taken("index build", UNIX_EPOCH, None),
    git: AnswerObservation::taken("git read", UNIX_EPOCH, Some(Duration::from_secs(120))),
};
let json = serde_json::to_value(&now).unwrap();
assert_eq!(json["git"]["stale_after"], "1970-01-01T00:02:00Z");
assert!(json["index"].get("stale_after").is_none());
let back: RepositoryObservations = serde_json::from_value(json).unwrap();
assert_eq!(back, now);

property	type	required	description
index	AnswerObservation → AnswerObservation	yes	When the index was built: the objects, the kinds, the diagnostics.
git	AnswerObservation → AnswerObservation	yes	When git was asked: the branch, the head, the working tree.

Used by RepositoryInfo

RepositoryReport

object

The repository, its layer, its git state, and the state of this process's index.

property	type	required	description
repository	RepositoryInfo → RepositoryInfo	yes	The repository: root, layer schema, sections, git state, discovery mode, source classes, kind sources.
state	State → State	yes	`ok` when every discovered file became an object, `degraded` otherwise.
objects	integer (uint)	yes	How many objects the index holds.
kinds	map of integer (uint)	yes	Objects per kind.
diagnostics	array of Diagnostic → Diagnostic	yes	Every diagnostic the index produced.
capabilities	Summary → Summary	yes	The capability registry, counted.

Used by repository.info

ScopeReport

object

The scope: the declaration as read, its origin, and every tracked file against it.

property	type	required	description
origin	Origin → Origin	yes	`repository` when the manifest names a scope section, `distribution` for the default.
path	string	yes	The file the declaration was read from.
declaration	Declaration → Declaration	yes	The declaration as read.
tracked	Tally → Tally	yes	Every tracked file judged by name and size, counted; the out ones listed.

Used by repository.scope

State

"ok" | "degraded"

Whether every discovered file became an object.

okEvery discovered file became an object.
degradedAt least one file could not be read; the diagnostics say which.

Used by RepositoryReport

Tally

object

Every tracked file against the scope, counted.

property	type	required	description
files	integer (uint)	yes	How many tracked files were judged.
in	integer (uint)	yes	How many are in.
out	integer (uint)	yes	How many are out.
by_reason	map of integer (uint)	yes	How many are out for each reason present.
out_files	array of OutFile → OutFile	yes	Every tracked file that is out, with its reason and the rule that decided.

Used by ScopeReport

Verdict

"in" | "out"

In or out.

inRead.
outNever read; the reason says why.

Used by Classification

HTTP API: repository

repository

Repository and index state

Try it

Responses

The repository scope

Try it

Responses

Judge a path against the scope

Query parameters

Try it

Responses

Schemas

Category

Classification

Declaration

Fixtures

GitInfo

GitState

Origin

Out

OutFile

Reason

RepositoryInfo

RepositoryObservations

RepositoryReport

ScopeReport

State

Tally

Verdict