Integrations
REST API
An overview of the node's REST API, the tokens it accepts, a few examples with curl, and the live event stream.
The web UI is built on the node’s REST API, so anything you can do in the UI you can
script. The API lives under /api/v0 on every node, takes and returns JSON, and uses
the same permissions as the UI.
v0 means the API can still change between releases. Breaking changes are called out
in the changelog.
Tokens#
Send a token in the Authorization header:
Authorization: Bearer <token> The API and /mcp take only Bearer. Basic credentials (curl -u) work for git, not here.
Three kinds of token work with the API.
A session, from signing in with a handle and password. It lasts 12 hours:
curl -sS -X POST https://moru.example.com/api/v0/sessions \
-H 'Content-Type: application/json' \
-d '{"handle": "mira", "password": "…"}' { "token": "…", "handle": "mira", "role": "admin", "expires_ms": 1794282707594 } DELETE /api/v0/sessions/current signs that token out again.
A token for scripts, minted on the node by an operator. It lasts 7 days unless you
pass --ttl. The token goes to stdout, so you can capture it:
MORU_TOKEN=$(moru-node --data /var/lib/moru create-user-token mira --ttl 30d) This also works for people who sign in with an AT Protocol account and have no password.
No token, for reading public repositories. Read routes answer anonymous callers for public repositories, and answer 404 for private ones, as if they didn’t exist.
Access tokens from Account → Access tokens for git don’t work with the API. They only let git fetch and push, and the API answers them with 403 “access tokens only work with git; sign in to use the API”. See Repositories.
Errors#
Errors come back as JSON with a status code:
{ "error": "only admins can do this" } Some also carry a machine-readable reason. Every response has an x-request-id header; give it to whoever runs the node, and they can find your request in its logs.
Examples#
These use MORU_TOKEN for the token and moru.example.com for the node.
Who am I:
curl -sS https://moru.example.com/api/v0/whoami -H "Authorization: Bearer $MORU_TOKEN"
The repositories you can read, with your role in each:
curl -sS https://moru.example.com/api/v0/repos -H "Authorization: Bearer $MORU_TOKEN" Create a private repository whose main starts with a README:
curl -sS -X POST https://moru.example.com/api/v0/repos \
-H "Authorization: Bearer $MORU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"repo": "acme/timetable", "visibility": "private", "readme": true}' Open changes, newest first (status takes a comma-separated list of open, approved, proposed, merged, conflicted and closed; limit goes up to 200; q matches the title or the start of the change ID):
curl -sS 'https://moru.example.com/api/v0/repos/acme/timetable/changes?status=open&limit=20' \
-H "Authorization: Bearer $MORU_TOKEN" Each change, in the list and from GET /changes/{change}, has base: whether its latest
revision still applies to its target branch. state is current (it sits on the
branch’s tip), applies (behind, but merges cleanly) or conflicts; onto is the
target commit it was checked against, and paths the conflicting files. A single change
also has revision and checked_ms. base is null when the change isn’t open, hasn’t
been checked yet, or the check failed, and on a node whose git is older than 2.40. Add base=conflicts to the list to get only the
changes that conflict:
curl -sS 'https://moru.example.com/api/v0/repos/acme/timetable/changes?status=open&base=conflicts' \
-H "Authorization: Bearer $MORU_TOKEN" File a request and start an agent on it in one call:
curl -sS -X POST https://moru.example.com/api/v0/repos/acme/timetable/requests \
-H "Authorization: Bearer $MORU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"title": "Show the next departure on the stop page",
"body": "The stop page lists every departure of the day. Put the next one at the top.",
"criteria": ["The next departure is shown first", "Tests cover the stop page"],
"attempt": {"kind": "agent", "profile": "claude-sonnet"}
}' The answer (201) is the request, with attempt_id when the agent started. If the
request was filed but the attempt couldn’t start, it has attempt_error instead, and
the request still exists: don’t send it again. profile is one of the node’s profiles; GET /api/v0/profiles lists them. Add "target": "release" to have the work merge into a branch other than the default one;
the branch must exist.
What’s there#
An overview by area. Paths are under /api/v0, and {owner}/{name} is a repository.
| Area | Routes |
|---|---|
| You | GET /whoami, POST /sessions, DELETE /sessions/current, GET and POST /access-tokens, GET and PATCH /preferences |
| Repositories | GET and POST /repos, GET and DELETE /repos/{owner}/{name}, POST /repos/import, PUT and DELETE /repos/{owner}/{name}/watch |
| Code | /repos/{owner}/{name}/refs, /tags (?q=, offset, limit), /tree, /blob/{path}, /raw/{path}, /commits, /commits/{oid}, /readme (all GET) |
| Changes | GET /repos/{owner}/{name}/changes, GET and PATCH /changes/{change}, GET /changes/{change}/revisions/{n}/diff, POST /changes/{change}/merge, GET /changes/{change}/verify |
| Requests | GET and POST /repos/{owner}/{name}/requests, GET /requests/similar, GET /requests/templates, GET and PATCH /requests/{id}, POST /requests/{id}/accept, /decline, /move, /close, /reopen, /attempts, GET /requests/{id}/prompt-preview, POST /requests/{id}/attempts/{attempt}/cancel and /stop-rounds |
| Bake-offs | GET /repos/{owner}/{name}/bakeoffs/{id}, POST /bakeoffs/{id}/decide, POST /bakeoffs/{id}/cancel |
| Tracker | GET /repos/{owner}/{name}/tracker, POST /tracker/labels, /labels/usual, PATCH and DELETE /tracker/labels/{id}, POST /tracker/milestones, PATCH /tracker/milestones/{id}, POST /tracker/milestones/{id}/close and /reopen |
| Discussions | GET and POST /repos/{owner}/{name}/changes/{change}/discussion, with reactions, threads/{thread}/replies, /resolve and /unresolve below it; the same under requests/{id} and commits/{oid} |
| Access | GET and PATCH /repos/{owner}/{name}/settings, /collaborators, GET and POST /orgs, /orgs/{name}/members/{handle} |
| Work | GET /profiles, GET /runners, GET /repos/{owner}/{name}/jobs, GET /jobs/{id}/logs |
| CI | GET and POST /repos/{owner}/{name}/ci/runs, GET /repos/{owner}/{name}/ci/runs/{id}, GET /repos/{owner}/{name}/ci/runs/{id}/jobs/{job}/logs, GET /repos/{owner}/{name}/ci/runs/{id}/artifacts and /artifacts/{artifact}, POST /repos/{owner}/{name}/ci/runs/{id}/cancel and /rerun, GET /repos/{owner}/{name}/ci/workflows, GET and PUT /repos/{owner}/{name}/policy |
| Inbox | GET /attention, GET /notifications, POST /notifications/read |
| Webhooks | /repos/{owner}/{name}/webhooks; see Webhooks |
| Node | GET /health (no token), GET and POST /people; for site admins GET /hosts, GET /nodes, GET /nodes/local |
Lists that can be long (changes, requests, CI runs) take limit and a before cursor
for the next page.
Requests, triage and planning#
POST /repos/{owner}/{name}/requests is open to anyone signed in who can read the
repository, unless its settings say "requests": "writers". Without write access the
request waits in triage ("status": "triage"), and the body may not carry criteria or
an attempt (403). Each account may file 10 such requests an hour (429 with Retry-After after that). The body takes kind (bug, feature, task) and template (a key from GET /requests/templates); a request filed from a template by someone with
write access gets the template’s labels.
People with write access triage with POST /requests/{id}/accept (409 unless it’s in
triage) and POST /requests/{id}/decline with {"reason": {"kind": "duplicate", "of": "<request id>"}}, or wont_do, not_reproducible, spam, or {"kind": "other", "text": "…"}. Starting an attempt on a
request in triage accepts it too. A request declined as spam is a 404 for everyone
without write access.
PATCH /requests/{id} also takes the planning fields, for people with write access: kind, priority (urgent, high, medium, low), milestone (an ID from the
tracker), rank (a backlog key), labels: {"add": [...], "remove": [...]} (label IDs)
and relations: {"add": [...], "remove": [...]}, each relation {"relation": "parent" | "blocked_by" | "duplicate_of", "request_id": "…"}. null clears kind, priority or milestone. Only what changes is written. A parent that would
make a loop is refused (400). The request’s detail has relations.out and relations.in,
each with the other request’s title and status.
GET /repos/{owner}/{name}/requests filters with status (comma-separated, triage included), kind, priority, milestone (none for unset), label (an ID), author, assignee, profile and q, and sorts with sort: updated (the default, and the only
one before pages), newest, priority, rank or votes. Rows carry labels, votes, kind, priority, milestone, rank and triage.
POST /requests/{id}/move with {"after": "<id>", "before": "<id>"} (either may be left
out) puts a request between those two in the backlog; 409 when they aren’t next to each
other any more. GET /requests/similar?title=…&exclude=…&limit=… lists requests whose
titles share words with title. GET /requests/{id}/prompt-preview, for people with
write access, returns the request’s part of an agent’s instructions as {text, trust}.
GET /repos/{owner}/{name}/tracker returns the labels (with open_requests) and the
milestones (with their requests counted by status). Writing labels and milestones needs
write access; the answer is the tracker again, and creating one adds its new id.
Reactions go to POST …/discussion/reactions with {"comment": "<comment id>", "emoji": "+1", "on": true}; leave comment out to react to
the request or change itself. The emoji are +1, -1, laugh, hooray, confused, heart, rocket and eyes. A discussion lists reactions on its subject and on each
comment as {emoji, count, mine}.
Job logs need write access to the repository: GET /jobs/{id}/logs and the runner
details in GET /repos/{owner}/{name}/jobs. A CI job’s logs are also at GET /repos/{owner}/{name}/ci/runs/{id}/jobs/{job}/logs (job is a job’s job_id in the
run), with ?tail= (and before=) or ?after= as for /jobs/{id}/logs. There, on a
public repository, anyone who can read it may read them, without a token too; on a
private one, people with write access. GET /repos/{owner}/{name}/ci/runs/{id} says which
with logs, and has each job’s detail and outputs when it’s true. Its run also
has run_number and run_attempt (re-runs keep the number and count up the attempt), schedule (expr and timezone, for a scheduled run, else null) and actions, the
resolved actions its jobs use (uses, commit, tree, locked): their own steps’ uses:, and the nested ones their runners say they ran. Each job also has containers,
the images it used as its runner reported them (role: job, service or action; name, image and digest; for an image built from a Dockerfile, digest is its image
ID), [] when none, for anyone who can see the run. A planned job’s needs_containers says whether it needs a runner with containers (container:, services: or its own docker:// steps).
A run’s artifacts follow the same rule as its logs. GET /repos/{owner}/{name}/ci/runs/{id}/artifacts lists them, oldest first, each with run_id, job_id (the job that uploaded it last), name, size, sha256, created_ms and expires_ms. GET /repos/{owner}/{name}/ci/runs/{id}/artifacts/{artifact} downloads
one as a zip, with Content-Disposition: attachment, its Content-Length and its
SHA-256 in x-moru-sha256. An expired artifact is a 404. In a browser, the run page’s
address plus /artifacts/{artifact} (/r/{owner}/{name}/ci/{id}/artifacts/{artifact})
serves the same file to a signed-in person without a token header.
POST /repos/{owner}/{name}/ci/runs starts a workflow by hand, for people with write
access: {"workflow": "deploy", "ref": "main", "inputs": {"target": "prod", "dry-run": true}} (ref defaults to the default branch). inputs are the workflow’s manual inputs by name:
a string, true/false for a boolean, a number for a number, one of the options for a
choice (a string that reads as the right kind works too). Defaults fill the rest (with
no default: "" for a string, false for a boolean, the first option for a choice, and
a number is left out); an
unknown name, a missing required input or a value of the wrong kind is a 422 that names
each one. All values together may be at most 65,535 bytes. A native job reads them as MORU_INPUT_<NAME>, a GitHub workflow as inputs.<name> (typed) and github.event.inputs.<name> (text). A run keeps its inputs, so a re-run uses them again.
Inputs aren’t secret: anyone who can see the run sees them in GET /repos/{owner}/{name}/ci/runs/{id} (run.inputs), so don’t pass tokens or
passwords there. GET /repos/{owner}/{name}/ci/workflows lists each workflow’s inputs (name, kind, description, default, required, options).
A run whose workflow uses an action that .moru/actions.lock doesn’t list has unlocked: true: the node looked the action’s tag or branch up when the run started. A
re-run uses the same commits. GET /repos/{owner}/{name}/ci/workflows marks each uses entry locked or not, and has lock_error when the lock file doesn’t read.
Scheduled runs start from the default branch’s workflows, at most once every 5 minutes
per schedule, and act for the person in the policy’s schedule_as (by default the
repository’s owner, when that’s a person; an organization’s repository runs no
schedules until it’s set). GET /repos/{owner}/{name}/ci/workflows lists each
workflow’s schedules (cron, timezone, next_runs in milliseconds, more_often_than_5_minutes) and has schedule_as: did, handle, set (whether
it’s the setting rather than the default), on, and why when schedules are off. A
repository runs at most 50 schedules; a workflow with schedules past that has a note
naming them. Re-running a scheduled run is a 409 once the default branch has moved on.
PUT /repos/{owner}/{name}/policy, for repository admins, sets the merge rules require_pinned and required_ci (a list of workflow/job names), require_locked_actions, which refuses CI runs whose workflow’s own uses: references
the lock file doesn’t list, and schedule_as, the DID of a person who can write to the
repository (a 422 otherwise; null goes back to the default). Fields left out of the
body keep their value, and the answer is the whole policy. An action the workflow uses
can itself use other actions: when moru-runner ci lock wrote the lock, it followed
those nested references and locked them too; otherwise the runner looks them up when the
step runs, and the run’s record lists them as unlocked. GET /repos/{owner}/{name}/policy reads it, for anyone who can read the repository.
GET /hosts lists the hosts the node knows: its own, every trusted attester, and every
host whose doc or revocations it found in a repository. Each row has the revocations the node knows,
with where it learned them (repo, record, registry, feed), and, for a did:plc host, when its PLC directory log was last fetched. On a host with many
nodes, each node keeps its own list: ?node=<did> asks that node, and without it the
control node answers. Only a signed-in admin’s session is sent on to another node; with
a personal access token, ?node= naming any node but the one answering gets a 404.
GET /nodes lists the nodes of this host, with their repo counts, last reports and the
moves between them; the control node answers it, from whichever node you ask. GET /nodes/local is the short version from the node you ask, read from its own copy of
the node list: each node’s key_id, did, role, state and whether the host’s
certificate for it holds now (trusted). Both give a revoked node’s revoked_at_ms, the
time its ops stop being trusted from (null for the others). It still answers while the control node is
down (for as long as the node accepts your session). On a node that runs on its own,
both answer "multi_node": false and no nodes.
To empty a node, a site admin sends POST /nodes/{did}/drain with {}, or with "to" (the nodes to move to, by DID or key ID) and "drain_ms" (how long each repository’s
running jobs may go on, 10 minutes if absent, at most 24 hours). It answers 202 with
the drain’s id, or at once with the reason: 400 for a "drain_ms" over 24 hours, 422
when "to" names a node the host doesn’t have or only nodes that can’t take
repositories (the node itself, a control node, a node being drained, one that isn’t
active or is too far apart), 404 for a node the host doesn’t have, and 409 when the node
isn’t active, is being drained already, there’s no other node to move to, or a node of
the host is too far apart for any repository to move. On these routes a 409 is about
the host’s state, never about what you sent. The drain moves one repository at a time,
and the node takes no new repositories from then on. POST /nodes/{did}/drain/abort stops it (202 with the drain’s id, 409 when none is running), and once no drain of it
runs, POST /nodes/{did}/drain/undo lets the node take new repositories again (200 with did and whether it changed, or 409
while a drain runs). Each node in GET /nodes and GET /nodes/local has draining_ms, when its drain started (null when it isn’t draining). GET /nodes lists
the drains under drains, newest first: every one still running and the latest of those
that finished. Each has its state, how many repositories it moved (moved_count),
those that stays and not_moved with why, and the move in flight (current); the
names of the repositories it moved are in GET /nodes/requests/{id} (drain.moved).
Its moves has every move that hasn’t finished and the latest of those that have,
leaving out the ones a drain moved, since the drain counts them; a drain’s move that
failed stays listed, with its message.
The event stream#
GET /api/v0/events is a server-sent events stream of what happens on the node. The UI uses it to update pages live.
curl -sSN 'https://moru.example.com/api/v0/events?repo=acme/timetable&since=now' \
-H "Authorization: Bearer $MORU_TOKEN" id: <epoch>.4812
event: change.revised
data: {"id":4812,"repo":"acme/timetable","kind":"change.revised","payload":{…},"created_ms":1794239507594} | Parameter | |
|---|---|
repo | One repository’s events. Without it you get every repository you can read, plus your notifications. |
since | Where to start: an event id, or now for only new events. Without it the stream starts with every event the node has kept. |
only | A comma-separated list of event kinds to send. |
To resume after a dropped connection, send the last id you saw as Last-Event-ID (or since); the stream carries on from there. If the node rebuilt its index or
deleted old events in the meantime, the stream starts with a reset event: reload
what you show, then carry on.
What you receive follows your access. A repository’s events go to people who can read
it; job events, logs included, only to people with write. If your access is taken
away, the events stop without a reconnect, and the stream ends when the token expires
or is revoked. The stream without repo is for people: agents and runners must name a
repository.