API and agent tools

Every operation Mainworthy has, with its address, the capability it needs and its input. The web UI, the command line and an agent's tools all call these same operations. The command line and the HTTP API reach all nineteen. An agent's tools are ten of them.

Call an operation #

An operation is one POST with a JSON body. An operation on a project is at /api/p/<project>/<operation>. An operation on the instance (admin, session, credential and invitation) is at /api/<operation>, and only there: under a project's address it is answered not_found, with the address to use.

$ curl -s -X POST http://127.0.0.1:7357/api/p/scratch/find \
    -H 'content-type: application/json' \
    -d '{"in":"cases","limit":2}'
{"ok":true,"result":{"count":0,"items":[],"cursor":null},"seq":1}

The OpenAPI document at /api/openapi.json describes each operation's input and successful reply, including the fields inside result. The registry supplies both schemas. seq is required and is null for an instance operation. A field declared nullable may hold null; an optional field may be absent. Replies selected by an action or a ref are described as alternatives.

A reply that ran has ok: true, the result, and seq, the project's sequence number at that point. Pass seq back to since to ask what changed after it.

A reply that did not run has ok: false and an error with a code and a message:

{"ok":false,"error":{"code":"not_found","message":"no operation named nope"}}

Authenticate #

Send a token as Authorization: Bearer <token>. A server in local mode trusts requests from the same machine and needs none. People, agents and pipelines explains how to make a token and what it may do.

Sign in as a person #

A browser signs in with these requests and then holds a session cookie. They are not operations: nobody is signed in yet, and a password never passes through an operation. Each POST refuses a request that a browser makes from another site's page and accepts one that names no site (a script, curl); GET /api/login/methods answers anybody. Each takes JSON and answers with the same envelope as an operation, without seq. People, agents and pipelines says what they are for.

A body holds one of these shapes and nothing beside it. GET /api/session says who is signed in, which session the request came by (session), whether the caller owns the instance (owner) and, for a person, what they sign in with (credentials: whether they have a password, and how many passkeys).

A signed-in person registers a further passkey with the credential operation: passkey.begin answers the options for navigator.credentials.create, and passkey.add takes what the browser returned and a label. Both are for a browser that is signed in, and the session that begins a registration is the one that finishes it. A token is refused with forbidden, as it is when it tries to set a password.

Send a write twice safely #

A write takes cmd, an id you choose for that one request. Sent again unchanged, the server returns the first reply and writes nothing. Sent again with other content, it is refused with conflict. If you lost the reply, ask the command operation what became of the id.

The machine-readable description #

GET /api/openapi.json returns an OpenAPI 3.1 document of every operation. The server builds it from the same list as this page on each call. It needs no token.

Follow changes #

GET /api/p/<project>/events is a stream of server-sent events, one for each write to the project. It needs the read capability. A client that misses an event loses nothing: it reads again, or asks since.

Operations #

propose #

Create or change cases, folders, links or the policy. Saving and proposing are the same call; policy decides what happens next.

report #

Record results: a parsed CI report, one manual result, or an agent's batch. The producer is the token's actor.

claim #

Record a review and what it found. A review with no findings is still recorded.

change #

Say that a change ended (merged, or closed without merging) or is open again. An ended change is not asked about.

plan #

Start a run: choose cases, say which results count and what completes it. Evidence already recorded fills it at once.

decide #

Answer a question, or withdraw a decision. Policy says whether your answer settles it, is advice, or is refused.

inbox #

The queue: every question that needs an answer, most blocking first. With state=decided: the ledger.

get #

Read cases, questions, runs, tests or proposals by ref.

find #

Search and list: cases (by text, folder, tag), tests, runs, slots of a run, folders, requirements, changes.

impact #

The cases a change touches and why, with what was already reviewed or decided. Where to look, instead of the whole suite.

since #

What changed since a cursor: cases with what changed in each, and questions that were settled.

gate #

The verdict for a commit, a change or a run: passed, failed (needs a fix), blocked (needs a decision), pending (needs evidence).

history #

The versions of a case, or the step-level diff between two of them.

timeline #

One timeline for a case: versions, moves, results from every producer, findings, reviews and its questions.

check #

Check the suite for structural problems: cases with no steps or no expected result, duplicate titles, dangling links.

command #

What became of a command you sent under an idempotency key: not recorded, begun, or done with its reply.

admin #

Projects, actors, grants and tokens. There are no seats: an actor is free, and a token carries what its actor may do.

session #

Your browser sessions: list them, and end one. An admin who is a person lists and ends anyone's.

credential #

How a person signs in: list your password and passkeys, register a passkey, remove one. An agent is refused: it signs in with a token only. A password is set in the web UI, never here.

invitation #

Invite a person with a link, since there is no mail: make one, list them, revoke one. The link is shown once.

Agent tools #

An agent that connects over MCP gets these operations as tools, with the same inputs. Each tool has a compact output schema for { result, seq }, the result's top-level type and its required fields. Nested fields and alternative replies are described in full by the OpenAPI document. Most input-field descriptions are in the shipped skill reference; tool schemas retain guidance for commit reuse, question answers and review filtering. Let an agent in explains how to connect one.