HTTP API
The UI is a client of a small HTTP API on the same port, and an agent can use it too. Prefer it to editing files
while the server runs: its writes are atomic and are merged with concurrent edits
(how). It answers on http://localhost:5622 only, and only to localhost
requests; writes must be JSON, except an image upload, whose body is the image, and a DELETE, which has none (see
Localhost security).
P=my-feature; R=my-service; SHA=0a1b2c3d # a short or full shaBASE=http://localhost:5622/api/projects/$P/repos/$R/commits/$SHAJ='Content-Type: application/json'
curl -s $BASE/review | jq '.threads[] | select(.resolved != true and .publish != true)' # open threadscurl -s -X POST -H "$J" $BASE/threads/<tid>/comments -d '{"author":"claude","body":"…"}' # replycurl -s -X PATCH -H "$J" $BASE/threads/<tid> -d '{"resolved":true}' # resolvecurl -s -X PUT -H "$J" $BASE/pr -d '{"title":"…","body":"…"}' # null clears a fieldcurl -s -H 'Content-Type: image/png' --data-binary @shot.png \ "http://localhost:5622/api/projects/$P/assets?alt=Screenshot" | jq -r .markdown # add an imageMore recipes are in the agent guide.
Endpoints
Section titled “Endpoints”… below is /api/projects/:p/repos/:r/commits/:sha, where :sha is a short or full sha.
| Method | Path | |
|---|---|---|
| GET | /api/projects | Projects: slug, title, description, error (a project.yaml that can’t be read), repo names/count (repoCount), branches, commit count (commitCount, without follow-on stacks and merged PRs; followOnCount, mergedCount), totals (the aggregate: stacks, prs, additions, deletions, with followOn and merged beside them), readiness (PRs by status, follow-on stacks left out: {draft, ready, published, merged}), archived, example, hidden (hidden: true in project.yaml: the UI leaves it off the root page and the switcher; it’s still listed here), unresolved count, modified (the newest write to any of its files), activity ({at, kind}: the newest comment, live commit (author date), merged (landed.at) or file write, edit), thumb (the thumbnail’s version), after and next (linked projects: the predecessor’s slug or null, the successors’ slugs), warnings (project-level, e.g. a bad after:); plus newExamples (example projects new in this version, not added yet), exampleCount (how many example projects there are), projectsDir, home (the user’s home directory, so a client can show paths as ~/…) and examples: present, removed (removed earlier, restorable) or none. |
| POST | /api/examples | {}: add the example projects (create, restore removed ones, leave existing ones). Returns {created, restored, existing, removed} (slugs); 201 if it created any, else 200; 409 if a project of yours has an example’s name. The git work doesn’t block the server; a second request while one is running gets the same result. |
| POST | /api/examples/remove | {}: remove them (rename each project.yaml to a .bak; nothing deleted). Returns the same shape; 409 while they’re still being added. |
| GET | /api/projects/:p/thumb.svg | The root page’s thumbnail of the project (a lane per repo, a bar per PR; see the root page), 280×150, or ?w=<200–800> wide (the card’s width, so it’s never scaled), light or dark with the page. ETag is the list’s thumb (at the default width), with Cache-Control: no-cache, so a revisit is a 304; same CSP as the stack pictures. |
| GET | /api/projects/:p | slug, title, file (its project.yaml), error; after ({slug, title} or null) and next ([{slug, title}]): linked projects; warnings (project-level); description, repos (range, errors, warnings, after: the predecessor’s range end in this repo or null, startsAfter: whether the range starts there), stacks (title, color, commit shas, warning, description, follow_on: true on follow-on stacks, weight; number, the 1-based position in stacks: that stack URLs use, null for an implicit group, which has `implicit: ‘unstacked’ |
| GET | /api/projects/:p/threads | Every thread with a comment in it, on every PR of the project (all repos and stacks, every commit in the range, published or not), as the Comments tab lists them: open threads first, then by last update, newest first. ?repo=<name> keeps one repo’s PRs, and ?repo=<name>&stack=<ref> one stack’s (:ref as in the stack picture’s URL below). Returns {threads, problems}. Each of threads is {repo, sha, position, thread, updated}: the PR’s full sha and its 1-based position in its repo, the thread as …/review gives it (placed on that commit, outdated set, carried over after a rebase), and updated, its newest comment or reply, written or edited (ISO, or null). problems are review files that aren’t valid YAML, whose threads are left out: {repo, sha, file, error}. Read-only. 400 for ?stack= without ?repo= or a malformed ref, 404 for no such repo or stack. |
| GET | /api/projects/:p/github | The project’s GitHub status, from the cache (no network): enabled (the sync is on and the project takes part), optedOut (github: {sync: off}), source, maxAgeMs, fetchedAt (the oldest of its GitHub repos’ last good fetches, or null), error (a repo’s last attempt failed), repos ([{key, host, fetched_at, error, prs}], key being owner/repo), prs (by owner/repo#number: {url, number, state, draft, checks, approved_by, changes_requested_by, tone: 'approved'|'blocked'|null, threads: {total, open, answered, resolved}, conversation, first_open, fetched_at}) and aliases (<repo>#<number> → that key, for PRs a prs file records by number only). |
| POST | /api/projects/:p/github/refresh | {reason: 'button' | 'focus'}: fetch the project’s PRs from GitHub now. button always fetches (all of them, merged and closed too); focus (the page came back into view) only if the sync is on for the project and the cache is over a minute old. One query per GitHub repo, shared with any fetch of it already running. Returns {results: [{key, host, fetched, skipped?, error?, missing?}], github} (github as the GET above). |
| PUT | /api/projects/:p/description | {description: string | null}: the project intro (null or blank removes it), up to 256 KB. Returns {description, file}. |
| PUT | /api/projects/:p/repos/:r/stacks/:n/description | {description, title?}: stack n’s note (1-based in stacks:). A title that no longer matches is a 409. Returns {description, title, file}; 404 for no such stack. |
| POST | /api/projects/:p/assets | Upload an image: the body is the image itself, with its type as the Content-Type (image/png, image/jpeg, image/gif, image/webp or image/svg+xml), up to 5 MB. Optional ?alt=<text>. Returns {name, markdown, created} (201; 200 with created: false if the same image was already there). See Images. |
| GET | /api/projects/:p/assets/:name | An image, by its <hash>.<ext> name (anything else is a 404). Served with its type, X-Content-Type-Options: nosniff, Cross-Origin-Resource-Policy: same-origin and Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline', so an SVG opened directly can’t run script. |
| GET | … | project, projectTitle, repo, repoPath, branch (the range’s end, a string), index, total; commit: metadata (including its branch record, github, status, landed), message body, files with old/new contents, stack (with position/count), project-wide prev/next, pr, review. |
| GET | …/review | The review: the file’s contents with threads placed on this commit (outdated, relocated line), plus file, target_file (absolute paths), matched_from, matched_by (set while the comments are still in an earlier commit’s file), carried_over ({from, by, saved}, or null: the review came from an earlier commit after a rebase, and whether it’s saved under this sha yet; the PR page shows it as a note), parse_error. |
| GET | …/pr | {title, body, title_source, body_source: 'commit'|'override', commit_subject, commit_body, branch, github, file, …} |
| PUT | …/pr | {title?, body?, branch?, github?, status?}. null clears a field; status is "draft", "ready" or null. See PR files. |
| POST | …/threads | New thread: {body, path?, side?, line?, start_line?, start_side?, author?, publish?}. Without path/side/line it’s a general thread. publish: true marks it for the GitHub PR (Threads for the GitHub PR). |
| POST | …/threads/:tid/comments | Reply: {body, author?}. |
| PATCH | …/threads/:tid | Any of {resolved: true | false}; {publish: true | false} (mark it for the GitHub PR, or not: the reviewer’s call); {published: {url, id?, at?} | null} (the agent’s record of the GitHub comment it posted: an http(s) url, the comment’s id, at defaulting to now; null clears it). 400 for anything else in those fields. |
| PATCH / DELETE | …/threads/:tid/comments/:cid | Edit {body} / delete. Only the reviewer’s own comments: an agent’s are never edited or deleted by the UI. |
| PUT | …/viewed | {path, viewed}: tick or untick a file’s Viewed box. |
| GET | …/github | What GitHub said about this PR, from the cache (GitHub status): the whole snapshot (the <number>.json in the data directory), or null if it hasn’t been fetched or the PR isn’t published. No network. |
| GET | …/stack.svg, …/stack.png | The stack picture with this PR highlighted. See below. |
| GET | /api/projects/:p/stack.svg, …/stack.png | The same for the whole project, nothing highlighted (as on the project page). |
| GET | /api/projects/:p/repos/:r/stacks/:ref/stack.svg, …/stack.png | Just one stack, nothing highlighted (as on its stack page). :ref is the stack’s number in stacks:, optionally with its title as a slug (2-groundwork), or unstacked / branch, resolved like the stack page’s URL (a reordered list follows the title). ?title=0, ?scale=linear and ?download as below; no scope. 400 for a malformed ref, 404 for no such stack. |
| GET | /llms.txt | For coding agents: how to set up a project, with this server’s data directory, existing projects and URLs (llms.txt). text/plain, Cache-Control: no-store. |
| GET | /llms-full.txt | The same, followed by the whole agent guide. |
| GET | /agent-guide.md | The agent guide on its own (text/markdown), with this server’s URLs. |
| GET | /api/me | The reviewer: {id, name} (see LOCAL_REVIEW_USER). |
| GET | /api/health | {ok: true, version}: the running version. |
| GET | /api/busy | {busy, version, counts: {save, snapshot, sync}}: the writes under way, which a restart would cut short (counts only, from memory; local-review busy asks it). |
| GET | /api/events | Server-Sent Events, below. |
Commit fields
Section titled “Commit fields”Each commit in GET /api/projects/:p (and the commit endpoint) carries:
status:draft,ready,publishedormerged. See Readiness.progress:{threads, resolved, files, viewed}: conversations (threads with at least one comment, outdated ones included) and how many are resolved, files changed and how many are marked Viewed.branch:{name, status: 'ok'|'moved'|'missing'|'discovered'|'merged', points_at?, discovered: string[]} | null. See Branches.github:{number, url, branch?, base?, created?, stack?, stacked_on?} | null.urlis''if the file gives only a number.
Stack picture options
Section titled “Stack picture options”The SVG is 680px wide; the PNG is drawn at 2x (1360px).
| Query | |
|---|---|
?scope=project (default), repo, stack | What’s in the picture. Only on the per-commit endpoint. |
?scale=sqrt (default), linear | How the +/− bars scale. |
?title=0 | Drop the project heading and summary line. |
?context=1 | A linked project (project and PR pictures): draw the predecessor’s stacks first in each shared repo, greyed out, unnumbered, out of the totals. |
?download | Add Content-Disposition: attachment. |
Events
Section titled “Events”GET /api/events is a Server-Sent Events stream. The server watches ~/.local-review/projects/ and, while at least
one stream is open, polls each repo’s branches every 2 seconds (running git only when the repo’s ref files change; see
Projects and repos). It sends an event: hello first, then each change as an event: change whose data
is one of these (so listen with addEventListener('change', …); onmessage sees nothing), and a comment line every
25 seconds to keep the connection open:
{"type": "review", "project": "my-feature", "repo": "my-service", "sha": "…"}{"type": "pr", "project": "my-feature", "repo": "my-service", "sha": "…"}{"type": "project", "project": "my-feature", "reason": "…", "repo": "my-service"}{"type": "projects", "reason": "…"}{"type": "github"}reason is config (project.yaml), dir, reviews, prs, head or refs (a repo’s branches moved; with
repo), or examples. github means a GitHub fetch finished (the server’s own, or local-review github refresh’s,
noticed within about 5 seconds): reload /api/projects/:p/github. The UI uses it to refresh, so edits to the files (by an agent or an editor) show up within about a second.
Errors
Section titled “Errors”Errors are JSON, {"error": "…"}, with a status code:
- 400: a malformed request: not JSON, a missing
body, astatusother thandraft/ready/null, a sha that isn’t hex or an ambiguous short one, a badauthor,path,lineorstart_side, a branch name git wouldn’t accept, a malformedgithub, apublishthat isn’t a boolean or a malformedpublished, a bad stack number or ref,?stack=without?repo=, a text over its size limit, an empty upload. - 403: a
Host(or, on a write, anOrigin) that isn’t localhost (see Localhost security); or editing or deleting a comment that isn’t the reviewer’s. - 404: no such project, repo, stack, asset, thread or comment, or a sha that isn’t in the repo’s range (it may have been
rebased away: look it up again in
GET /api/projects/:p). - 409: the file isn’t valid YAML, so the server won’t overwrite it until it’s fixed by hand (nothing is lost); or
a stack note’s
titleguard no longer matches; or the example projects can’t be added or removed (a project of yours has an example’s name, or they’re still being added); or an image upload whose name is taken by different contents. - 413: an upload over 5 MB. It’s refused from its
Content-Length, or as soon as a streamed body passes the limit, before being stored. - 415: a write (other than
DELETE) withoutContent-Type: application/json; on an upload, aContent-Typethat isn’t one of the image types, or contents that don’t match it (the file says it's PNG but its contents are JPG). - 500: anything else, with the message.