Skip to content

HTTP API: objects

The declarative objects of the repository's AI layer: rules, prompts, profiles, policy, documents, milestones, issues, claims, and whatever kinds the repository adds; listed, read by URI, and searched.

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.

objects

The declarative objects of the repository's AI layer: rules, prompts, profiles, policy, documents, milestones, issues, claims, and whatever kinds the repository adds; listed, read by URI, and searched.

GET /api/v1/object objects.get

Get one object

One object by URI (majordomus://<kind>/<identity>): metadata, provenance and content; a URI a query projects (majordomus://repository) answers that query as a JSON document. The same resolution serves the MCP resource read.

  • query
  • behaviorally_verified
  • benchmark required
  • cache disabled
  • MCP tool majordomus_get

Query parameters

nametyperequireddescriptionexamples
uri string yes `majordomus://<kind>/<identity>`, or a URI a query projects (`majordomus://repository`). first-object: "majordomus://adr/adr-0001"repository: "majordomus://repository"

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/object?uri=majordomus%3A%2F%2Fadr%2Fadr-0001"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

statusbodymeaning
200 ResourceView Get one object: 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/objects objects.list

List objects

List the declarative objects of the repository's AI layer, optionally by kind or tag.

  • query
  • behaviorally_verified
  • benchmark required
  • cache disabled
  • MCP tool majordomus_list

Query parameters

nametyperequireddescriptionexamples
kind string no Only objects of this kind; the kinds present are listed by `repository.info`. A kind the repository does not have is an invalid input, not an empty answer. first-kind: "adr"
tag string no Only objects whose metadata tags include this tag.

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/objects?kind=adr"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

statusbodymeaning
200 ObjectList List objects: 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/objects/verify objects.verify

Verify the index against the working tree

Read every file the layer was built from and compare it with what this process is serving. The index is built once at start-up and kept, which is what makes every other request cost nothing and what makes a file edited afterwards be served as it was; this is how a running server says whether that has happened, without being restarted to find out. A file that is one object is compared byte for byte; a collection file, whose objects the index keeps as members rather than as text, is compared by size, and every finding says which comparison was made. It reads every file of the layer, so it reports its progress file by file and stops when it is asked to.

  • query
  • behaviorally_verified
  • benchmark required
  • cache disabled
  • MCP tool majordomus_verify_objects

Query parameters

nametyperequireddescriptionexamples
kind string no Only objects of this kind.
limit integer (uint) no How many objects to read at most; every one of them when absent. bounded: 25

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/objects/verify?limit=25"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

statusbodymeaning
200 VerifyReport Verify the index against the working tree: 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.

AnswerView

object
A URI a query projects (majordomus://repository), answered: the same fields a client reads on an ObjectView where they apply, the answer itself as data, and the text resources/read returns for the URI.
propertytyperequireddescription
uri string yes The URI as given.
id string yes The capability that answered (repository.info).
kind CapabilityKind → CapabilityKind yes Its kind: query.
identity string yes The resource name a client lists (repository).
title string yes The capability's title.
description string | null no The capability's description, when it has one.
answer any yes The answer, as the capability's output schema describes it (capabilities.describe carries that schema).
provenance CapabilityProvenance → CapabilityProvenance yes Where the capability comes from: the Rust module it is composed in.
media_type string yes application/json.
content string yes The answer as text: byte for byte what resources/read returns for the URI.

Used by ResourceView

Comparison

"content" | "size"
How closely a file could be compared with what the index holds.

A file that is one object is compared byte for byte, because the index kept its whole content. A collection file holds one object per member, and what the index kept for each is that member as JSON rather than the file's text — so the strongest thing that can be said without re-parsing it is whether its size is what it was. The report says which comparison was made rather than implying the stronger one.

  • contentByte for byte against the content the index holds.
  • sizeBy size against the size the index recorded.

Used by DriftedObject

DriftedObject

object
One file of the layer that is no longer what the index read.
propertytyperequireddescription
path string yes Its repository-relative path.
standing ObjectStanding → ObjectStanding yes How it stands.
comparison Comparison → Comparison yes How it was compared.
objects integer (uint) yes How many objects of the index came from it.
example_uri string yes One of the URIs it holds, so a reader can see what is affected.
detail string yes What is wrong, for a person.

Used by VerifyReport

ObjectList

object
The answer of objects.list: the matching objects, summarised, in URI order.
propertytyperequireddescription
count integer (uint) yes How many objects matched.
objects array of ObjectSummary → ObjectSummary yes The objects, one summary each.

Used by objects.list

ObjectStanding

"current" | "changed" | "missing" | "unreadable"
How one file stands against what the index read from it.
  • currentIt is what the index read.
  • changedIt is there and it has changed since the index was built.
  • missingThe file the index read is no longer there.
  • unreadableIt is there and could not be read.

Used by DriftedObject

ObjectView

object
One declarative object of the repository's layer, as a client reads it.
propertytyperequireddescription
uri string yes majordomus://<kind>/<identity>.
id string yes The capability id, <kind>.<identity>.
kind string yes The kind the object was read as (rule, prompt, document, ...).
identity string yes The identity within the kind (majordomus.scope-integrity@1, continue, a path).
title string | null no The title the kind's title rule found, when it found one.
description string | null no The one-line description the kind's description field held, when it held one.
metadata any yes The parsed front matter or YAML, keys in the file's order.
provenance ObjectProvenance → ObjectProvenance yes Where the object came from: path, directory, source class, section, size, member.
media_type string yes IANA media type of content (text/markdown, application/yaml, application/json, text/plain).
content string yes The file as read.

Used by ResourceView

ResourceView

one of 2 variants
The answer of objects.get: what the URI resolved to, tagged by source the way a capability's provenance is.
variant A file of the layer, read as it is.
source"declarative"yes
variant A query with a resource exposure, executed and rendered as a JSON document.
source"builtin"yes

Used by objects.get

SearchHit

object
One search hit: the object, summarised, and the first matching line of its content.
propertytyperequireddescription
uri string yes majordomus://<kind>/<identity>.
id string yes The capability id, <kind>.<identity>.
kind string yes The kind the object was read as.
identity string yes The identity within the kind.
title string | null no The title, when the kind's title rule found one.
description string | null no The one-line description, when the kind holds one.
path string yes Repository-relative source path.
snippet string | null no The first line of content that matched, when one did.

Used by SearchResult

SearchResult

object
The answer of objects.search.
propertytyperequireddescription
query string yes The query as given.
count integer (uint) yes How many hits were returned.
limit integer (uint64) yes The limit that applied.
hits array of SearchHit → SearchHit yes The hits, in URI order, at most limit of them.

Used by objects.search

VerifyReport

object
The answer of objects.verify.
propertytyperequireddescription
files integer (uint) yes How many files were read.
current integer (uint) yes How many of them are what the index read.
drifted integer (uint) yes How many are not, of any kind of not.
objects integer (uint) yes How many objects of the index those files carry.
compared_by_content integer (uint) yes How many were compared byte for byte rather than by size.
fingerprint string yes The index fingerprint this process is serving.
index_is_current boolean yes Whether the index is still a true picture of the working tree, as far as this comparison can tell.
findings array of DriftedObject → DriftedObject yes The files that are not, with what is wrong with each.

Used by objects.verify

Searches the titles and descriptions of every page this site publishes.