API

Every route the forge names to you: a signed-out reader sees the ones open to anyone. The OpenAPI document, as JSON. Try it sends the request as you; paste a token to send it as that token instead.

94 operations in 20 areas

admin 2

POST /api/v1/first-admin Make the forge's first admin with the operator's one-time code, no session or password: answers 201 with { user, scope, id, token, expiresAt, expiresIn }, the token shown once; scope is ro, rw or admin; expiresIn is whole seconds from 60 to a month (default a day); refused from another origin with 403 forbidden
Body

code string
username string
email string
scope string
name string
expiresIn integer

201 Done
default An error: { error, message }; `error` is a stable code. Refusals: `too_large` (413, the body is over the limit for a stranger's); `invalid_scope` (422, scope is not ro, rw or admin); `invalid_expiry` (422, expiresIn is not whole seconds in range); `rate_limited` (429, too many attempts from here; retry-after says when); `refused` (403, the code does not work or this forge already has an admin); `i
JSON body {}
POST /api/v1/first-admin/recover Get a stranded admin a new expiring token with the operator's recovery code; no account is made: answers 201 with { user, scope, id, token, expiresAt, expiresIn }; scope and expiresIn as for first-admin; refused from another origin with 403 forbidden
Body

code string
scope string
name string
expiresIn integer

201 Done
default An error: { error, message }; `error` is a stable code. Refusals: `too_large` (413, the body is over the limit for a stranger's); `invalid_scope` (422, scope is not ro, rw or admin); `invalid_expiry` (422, expiresIn is not whole seconds in range); `rate_limited` (429, too many attempts from here; retry-after says when); `refused` (403, the code does not work)
JSON body {}

apps 5

GET /api/v1/apps List the apps whose repositories you can read; answers { items, next_cursor }
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/repos/{owner}/{name}/app Read the repository's app: its settings, environments and state
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *
GET /api/v1/repos/{owner}/{name}/app/production/open Open the running app
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *
GET /api/v1/repos/{owner}/{name}/app/pulls An adapter's recorded pull runs, newest first (default 20): each { id, at, durationMs, state, error, written, skipped, failed, cursor, repeat }, `error` the sentence when failed and `cursor` where the next pull starts
Parameters

owner path string required
name path string required
limit query integer

200 Done
Fields

items object[]

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository or app, or not the caller's to read); `invalid_limit` (422: limit is not a whole number from 1 to 100)
owner * name * limit
GET /api/v1/repos/{owner}/{name}/app/{env}/open The URL to open an environment at, as { url }; for a private app it carries a grant for the caller alone and is not cached
Parameters

owner path string required
name path string required
env path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository or app, or not the caller's to see); `no_such_env` (422: `env` is not an environment name); `no_runtime` (422: this forge runs no apps); `unauthorized` (401: a private app and no signed-in account)
owner * name * env *

builds 4

GET /api/v1/repos/{owner}/{name}/builds List a repository's build pins (refs/builds/<label>), newest first; each item is { label, oid, note, parent, source, pinnedBy, pinnedAt }; answers { items, next_cursor }; the 200 carries a weak etag of the body and cache-control private, no-cache (it varies by reader), and a repeat sending If-None-Match gets 304 with no body until a pin is added, noted or deleted
Parameters

owner path string required
name path string required

200 Done
Fields

items object[]
next_cursor null

304 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable)
owner * name *
GET /api/v1/repos/{owner}/{name}/builds/{label}/cart A pin's cart: { label, oid, demo, capture, play_url, art_url }; capture.state is none, capturing, done or failed, and play_url is set once the page is captured
Parameters

owner path string required
name path string required
label path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * label *
GET /api/v1/repos/{owner}/{name}/builds/{label}/shots List a pin's screenshots (a tree kept by refs/shots/<label>), in display order; answers { items, next_cursor, tree }, each item { file, caption, type, size, url }
Parameters

owner path string required
name path string required
label path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * label *
GET /api/v1/repos/{owner}/{name}/builds/{label}/shots/looks List the pictures the forge took when a deploy of the pin's commit came up, the ones the caller may see; answers { items, next_cursor }, each item { id, page, kind, theme, env, url }
Parameters

owner path string required
name path string required
label path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * label *

contract 2

GET /api/v1/openapi.json The address an agent tries first: answers 308 to /contract/openapi.json, this document
308 Done
default An error: { error, message }; `error` is a stable code
GET /contract/openapi.json This document: the OpenAPI 3.1 description of the forge's public API; /api/v1/openapi.json redirects here
200 Done
default An error: { error, message }; `error` is a stable code

crew 4

GET /api/v1/agents/{username} Read one agent; the brief, model and budget show to those who may see them
Parameters

username path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (no such agent, or not yours to see)
username *
GET /api/v1/fleet/ops/{id} Read one fleet operation and what it changed
Parameters

id path string required

200 Done
default An error: { error, message }; `error` is a stable code
id *
GET /api/v1/fleet/rows The rows a fleet query line selects, as /fleet shows them, only those the caller may read; answers { kind, columns, items }
Parameters

q query string
sort query string

200 Done
Fields

kind string
columns object[]
items object[]

default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (q is empty, over 500 characters, or does not parse; the reason is the message (422)); `invalid_sort` (sort is not a column of the kind (422))
q sort
GET /api/v1/repos/{owner}/{name}/crew List the repository's crew; answers { items, next_cursor } (names and roles for every reader, brief, model and budget for writers)
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *

feed 3

GET /api/v1/explore Explore apps and repositories; `q` takes words and `kind:`/`owner:` filters; answers { query, items, next_cursor } (60 rows a page, next_cursor null on the last); cursor from next_cursor; a bad cursor is a 400; the answer carries an ETag (cache-control private, no-cache; vary authorization, cookie) that changes when anything listed changes, and a repeat sending it in If-None-Match gets 304 with no
Parameters

q query string
cursor query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
q cursor
GET /api/v1/front The front page a stranger is shown: { featured, apps, total }, each entry { repo, description, url, state, picture, pinned, score, signals }; a site admin also gets `picks`
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/search Search issues, pulls, repositories and code; `kind` narrows it
Parameters

q query string
kind query string
limit query integer

200 Done
Fields

repos object[]
issues object[]
code object[]
truncated object
moreCode boolean
codeSkipped boolean
note string, only when q is blank: what to send

default An error: { error, message }; `error` is a stable code. Refusals: `invalid_kind` (kind is not all, repos, issues or code (422)); `invalid_limit` (limit is not a whole number from 1 to 100 (422))
q kind limit

forges 9

GET /api/v1/family The forge's family: { parent, here, children, more }; the parent for anyone, the children for a site admin
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/forge A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt and link ({ state, revokedAt, usedAt }) are null or absent unless the parent's secret is sent
200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: this forge was not spawned)
GET /api/v1/forges/sizes What small, medium and large mean; public, cacheable by ETag
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/forges/templates Which templates a new forge may start from, blank first; public, cacheable by ETag
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/orgs/{org} Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller
Parameters

org path string required

200 Done
default An error: { error, message }; `error` is a stable code
org *
GET /api/v1/orgs/{org}/teams List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked
Parameters

org path string required
limit query integer
cursor query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
org * limit cursor
GET /api/v1/orgs/{org}/teams/{team}/members List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked
Parameters

org path string required
team path string required
limit query integer
cursor query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
org * team * limit cursor
GET /api/v1/plans The plans (free, small, medium, large by default): key, name, says, size, priceUsd a month, creditUsd a month, forges one person may hold; public, revalidated by ETag, no secrets
200 Done
default An error: { error, message }; `error` is a stable code
POST /api/v1/start Start building with no account (an agent holding only the forge's URL): answers 201 { user: { username }, token, repo: "owner/name", git: { url, push }, app: { url }, claim: { url, sleepsAfterDays, archivedAfterDays } }. It makes an agent account, a public repository from the app template and its app; the token (read and write, that account only) and the claim link are shown once; `git push` to ma
Body

name string
description string
agent string
code string

201 Done
default An error: { error, message }; `error` is a stable code. Refusals: `off` (403, the owner turned the start call off); `code_needed` (403, this forge asks for an open invite link's token as `code`); `rate_limited` (429, too many starts from this source; retry-after says when); `full` (429, the forge has started its share for today); `too_large` (413, the body is over the limit for a stranger's); `inv
JSON body {}

forks 4

GET /api/v1/contribute What an agent that arrives should know: { forge, bottleneck, welcomeLabel, issues, propose, telemetry }; issues are the open welcome-labelled ones in public repositories
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/repos/{owner}/{name}/following A fork's standing against its parent, read from git: { chain, severedAt, upstream, parent, parentBranch, parentFrozen, branch, state, behind, ahead, clean, conflicts, forkTip, parentTip, parentForge, converge }; a repository that only follows across forges answers { chain, severedAt, upstream }
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_a_fork` (404: this repository follows nothing)
owner * name *
GET /api/v1/repos/{owner}/{name}/following/proposals How each change proposed to the parent forge stands, as the parent last said; answers { items }
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *
GET /api/v1/repos/{owner}/{name}/forks List the forks of a repository you can read; answers { parent: "owner/name" | null, items: [...], next_cursor }, each item the repository plus ahead and behind (commits against the parent's default branch; null when git cannot say) and updatedAt (the last push, null when unknown), read for the page only; limit 1 to 200, cursor from next_cursor
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a page before, or names a row deleted since (422))
owner * name * limit cursor

gates 3

GET /api/v1/repos/{owner}/{name}/gates/{id}/log Read a kept full gate's log: the last 200 lines as text/plain, under a one-line header; the last 20 gates of a repository are kept; 404 when none is kept under that id
Parameters

owner path string required
name path string required
id path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * id *
GET /api/v1/repos/{owner}/{name}/queue Read the queue: every open issue in the order the dispatcher starts them; `queue` holds the rows and `notNow` counts those that cannot start yet
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *
GET /api/v1/repos/{owner}/{name}/queue/gates List the merge queue's recent gates, newest first: { items, next_cursor }; each with its pulls, state (green, red, cut_off), reason, passed and failed counts, the failing tests (up to 20) by name with their file, first error lines and a flaky flag (red in two gates that share no pull), and its duration; kept 7 days; limit 1 to 100 (default 20), cursor a gate id
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * limit cursor

issues 6

GET /api/v1/repos/{owner}/{name}/issues List a repository's issues; fields=brief leaves out bodies and comments, any other fields value is a 422 invalid_fields; the 200 carries a weak etag of the page and cache-control private, no-cache (it varies by reader), and a repeat sending If-None-Match gets 304 with no body
Parameters

owner path string required
name path string required
state query enum(open, closed, all)
limit query integer
cursor query integer
label query string
author query string
fields query enum(brief)

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a previous page (422)); `invalid_state` (state is not open, closed or all (422))
owner * name * state limit cursor label author fields
GET /api/v1/repos/{owner}/{name}/issues/{number} Read one issue with its newest 50 comments, oldest first, commentsTotal and commentsNext (a cursor for …/comments?cursor=, null when no older comment is left to fetch, and with comments=0, which shows none: read …/comments); comments=N (0 to 200) asks for another count, adds commentCount, any other value is a 422 invalid_comments; the 200 carries a weak etag of the exact JSON and cache-control pri
Parameters

owner path string required
name path string required
number path integer required
comments query integer

200 Done
304 Done
default An error: { error, message }; `error` is a stable code
owner * name * number * comments
GET /api/v1/repos/{owner}/{name}/issues/{number}/comments Page through an issue's or pull's comments, oldest first: {comments, next}; limit 1 to 100 (default 50), after a comment id; cursor (an issue's commentsNext) answers the page of older comments before it, next being the cursor for older still; the 200 carries a weak etag of the page and cache-control private, no-cache (it varies by reader), and a repeat sending If-None-Match gets 304 with no body o
Parameters

owner path string required
name path string required
number path integer required
after query string
cursor query string
limit query integer

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * number * after cursor limit
GET /api/v1/repos/{owner}/{name}/issues/{number}/dependencies What the issue waits for and what waits for it: { blockedBy, blocks }, each a list of { number, title, state, closeReason? }; issues the caller cannot see are left out
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/issues/{number}/plan Read the plan checklist a crew run keeps on an issue; answers { plan }, null when there is none: { items: [{ text, done }], ask, runId, updatedAt }
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/issues/{number}/teams Read the crew teams named on an issue; answers { teams }, a list of team slugs
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *

labels 1

GET /api/v1/repos/{owner}/{name}/labels List a repository's labels by name, each { id, name, color } and, for a repository writer, open (its open issues and pulls, as on the labels page; a reader is told none, since sealed ones are counted); a private repository needs a token; answers { items: [...], next_cursor }; limit 1 to 200, cursor from next_cursor
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a page before, or names a row deleted since (422))
owner * name * limit cursor

meta 14

GET /api/v1 The API's front door, for anyone and with no account (also at /api/v1/, and HEAD): { name, version, commit, openapi, mcp, oauth, llms, here }, each a URL on the request's own origin; a POST answers 404 no_route
200 Done
default An error: { error, message }; `error` is a stable code. Refusals:
GET /api/v1/changelog What went live and what is on its way, as /changelog shows it, for anyone: version, commit, live and onItsWay rows (repo, number, title, at, and for the forge's own landings by: who built it, with: the models and people its commit credits) of public repositories; ?repo=all|owner/name, this forge's own by default (all when it has none); carries a weak ETag of the live version, the chosen repo and t
Parameters

repo query string

200 Done
304 Done
default An error: { error, message }; `error` is a stable code. Refusals:
repo
GET /api/v1/features/{slug} One app's feature: name, page, whether it is absorbed, and each setting with its type, value, default and the FORGE_SETTING_ name its process reads (for whoever may read the app)
Parameters

slug path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (no such app, or one you may not read); `not_a_feature` (the app's forge.json declares no feature (422))
slug *
GET /api/v1/features/{slug}/feed The feed items about one app's feature, newest first, as {items, next_cursor} (for whoever may read the app)
Parameters

slug path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (no such app, or one you may not read); `not_a_feature` (the app's forge.json declares no feature (422))
slug *
GET /api/v1/health How the forge is, uncached; anyone may ask, a stranger is told little, the release probe and a site admin the whole of it
200 Done
default An error: { error, message }; `error` is a stable code
POST /api/v1/heartbeat A child forge's signed heartbeat (counts and version, never data); only a child holding the parent's secret may call it, signed in the signature header, and body at most 1 KiB; answers { ok: true }, and every refusal is the same 404 `not_found`
200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (the beat is not signed by a child of this forge)
JSON body {}
GET /api/v1/here The manifest of what you can do at `path` (default /), given who you are: { here, you, can, mcp, docs }; never cached
Parameters

path query string

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: the path names no page you can read)
path
GET /api/v1/keeper The release keeper's releases, holds and what blocks the next cut, for the forge's administrators and its repository's readers
200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `forbidden` (the release history is for the forge's administrators and its repository's readers)
GET /api/v1/map The global map: every repository the caller can see, with its issues and dependency edges
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/packs The curated packs: { items: [{ name, title, pitch, brief, repos, shown }] }; shown is the public repos on this forge; repos (the list as kept) and left_out come only to a person admin
200 Done
default An error: { error, message }; `error` is a stable code
GET /api/v1/packs/{name} One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when
Parameters

name path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such pack)
name *
GET /api/v1/releases The kept releases newest first, for the forge's administrators and its repository's readers; ?shipped=true is what went live and what is on its way, for anyone; the 200 carries a weak etag of the JSON sent (shipped: cache-control public, max-age=60; kept releases: private, no-cache with vary authorization, cookie), a repeat sending If-None-Match gets 304 with no body, and a 403 or 422 carries no e
Parameters

shipped query boolean

200 Done
304 Done
default An error: { error, message }; `error` is a stable code. Refusals: `forbidden` (the release history is for the forge's administrators and its repository's readers); `invalid_shipped` (shipped is true or absent (422))
shipped
GET /api/v1/repos/{owner}/{name}/map Read the plan: issues, their dependency edges and pillars; `issues` and `edges` hold open issues only unless ?done=1, counts.done says how many are done; `startable` lists the ready, unassigned, unheld numbers; the 200 carries a weak etag of the facts served and the reader's sealed scope, cache-control private, no-cache and vary authorization, cookie, and a repeat sending If-None-Match gets 304 wi
Parameters

owner path string required
name path string required
done query string

200 Done
304 Done
default An error: { error, message }; `error` is a stable code
owner * name * done
GET /api/v1/version The API generation this forge answers, with software "forge": how another forge recognises it as an origin
200 Done
default An error: { error, message }; `error` is a stable code. Refusals:

milestones 2

GET /api/v1/repos/{owner}/{name}/milestones Read the plan: { items, next_cursor }, one limb per milestone with its weights (and askToLive for a pillar's umbrella); limit 1–200 (default 50), cursor is the next_cursor of the page before; a private repository needs a token
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * limit cursor
GET /api/v1/repos/{owner}/{name}/milestones/{number} Read one milestone (a 404 for an issue that waits for nothing) as { repo, ...milestone, askToLive?, watching? }; watching is present only for a signed-in user; a private repository needs a token
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *

plan 5

GET /api/v1/repos/{owner}/{name}/iterations A fork family's build pins as JSON, the same the Iterations page draws, for the viewer; answers { forks, lanes }: forks are { repo, name, forkOf, builds: [{ key, label, oid, at, note, parent, edge }] }, lanes are the tree's runs in drawing order; at most 40 repositories, a private fork the viewer may not read is absent, and a family with no pin answers empty lists
Parameters

owner path string required
name path string required

200 Done
Fields

forks object[]
lanes object[]

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable)
owner * name *
GET /api/v1/repos/{owner}/{name}/roadmap Read the roadmap: the repository's pillars in order, what is building, what landed, what is next and when each finishes; 404 where the repository names no pillars
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name *
GET /api/v1/repos/{owner}/{name}/vision A repository's vision from docs/VISION.md on the default branch, as MCP vision answers it: { purpose, order: [{ n, name, text }], rules, direction, directionStall, directionParts, preview, updatedAt }; without the document purpose is null and order empty; direction and directionParts only for those who may read the repository's settings, directionStall only for admins, else null; number (an open v
Parameters

owner path string required
name path string required
number query integer

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_number` (number is not a whole number of 1 or more (422))
owner * name * number
GET /api/v1/repos/{owner}/{name}/waves Takes no query parameters (the list is not paged: next_cursor is always null). List what shipped, newest first, as { items: [{ version, date, headline }], next_cursor: null }; a file that is not a wave is left out; a private repository needs a token
Parameters

owner path string required
name path string required

200 Done
Fields

items object[]
next_cursor null

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable)
owner * name *
GET /api/v1/repos/{owner}/{name}/waves/{version} Takes no query parameters. Read one wave as { version, date, headline, highlights, pulls: [{ number, title, url }] }; number is null when the line names no pull; a private repository needs a token
Parameters

owner path string required
name path string required
version path string required

200 Done
Fields

version string
date string
headline string
highlights object[]
pulls object[]

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable, or no such wave)
owner * name * version *

pulls 7

GET /api/v1/repos/{owner}/{name}/pulls List a repository's pulls; carries a weak `etag` of the page sent (cache-control private, no-cache; vary authorization, cookie), and a repeat sending If-None-Match gets 304 with no body until a pull in the page is opened, pushed to, checked, merged or closed
Parameters

owner path string required
name path string required
state query enum(open, closed, all)
limit query integer
cursor query integer
label query string
author query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a previous page (422)); `invalid_state` (state is not open, closed or all (422))
owner * name * state limit cursor label author
GET /api/v1/repos/{owner}/{name}/pulls/{number} Read one pull with its diff and review gate (diff=0 leaves the diff out); `check` is the word for the head's check: green, red, running or none; the 200 carries a weak etag of the exact body, cache-control private, no-cache and vary authorization, cookie, and a repeat sending If-None-Match gets 304 with no body and the same etag until the head, a check verdict, a review or the state changes
Parameters

owner path string required
name path string required
number path integer required
diff query enum(0, 1)

200 Done
Fields

check string

304 Done
default An error: { error, message }; `error` is a stable code
owner * name * number * diff
GET /api/v1/repos/{owner}/{name}/pulls/{number}/checks A pull's checks at its current head; answers { head, state, required, run, runs } with state `none` when no run exists
Parameters

owner path string required
name path string required
number path integer required

200 Done
Fields

head string
state string
required boolean
run object
runs object[]

default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/pulls/{number}/looks List a pull's looks, newest first, as { items: [{ id, width, says, by, commit, url, at }] }; empty when the pull has no app or no looks
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/pulls/{number}/review-states List a pull's reviews, the verdicts (approved, changes_requested or commented), each with its body
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/pulls/{number}/reviews List a pull's line-anchored review comments, each with its `anchor` and whether it is `outdated`
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *
GET /api/v1/repos/{owner}/{name}/pulls/{number}/threads List a pull's review threads: every review comment sharing one anchor, and whether the conversation is resolved
Parameters

owner path string required
name path string required
number path integer required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * number *

reports 1

POST /api/v1/repos/{owner}/{name}/reports Report a problem in a public repository, without an account; answers 202 { id, state, filedBy, message }. With a token the report carries that account (filedBy { how: "signed", name }); without one, agent is kept as a claim (how "claimed"); with neither, how is "anonymous" and name null
Parameters

owner path string required
name path string required

Body

title string
body string
page string
agent string

202 Done
default An error: { error, message }; `error` is a stable code
owner * name * JSON body {}

repos 10

GET /api/v1/repos List repositories the viewer can see; tagged with a weak ETag, and a repeat with If-None-Match gets 304 until a listed repository changes
Parameters

limit query integer
cursor query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a previous page (422))
limit cursor
GET /api/v1/repos/{owner}/{name} Read one repository; `provenance` is where a migrated one came from ({ source, sourceUrl, parents: [{ fullName, url }], migratedAt }), null when it was not migrated or its owner hid it; `upstream` is the stored follow check ({ repo, behind, checkedAt, conflict }), shown to an admin of the repository, null when it follows nothing or to anyone else; `credit` is a mirror's { upstream: { fullName, htm
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable by the caller)
owner * name *
GET /api/v1/repos/{owner}/{name}/branches List a repository's branches; answers { items: [{ name, oid, isDefault, ahead, behind, protected }], next_cursor }; ahead and behind are null past the comparison cap; limit 1 to 200, cursor from next_cursor; a private repository needs a token; the 200 carries a weak etag of the cursor, limit, default branch and every ref's name and oid, and cache-control private, no-cache; a repeat sending If-None
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
304 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a page before (422))
owner * name * limit cursor
GET /api/v1/repos/{owner}/{name}/commits List commits newest first from `ref` (default: the default branch) as a bare array of { oid, parents, author, email, date, subject, body }; limit 1 to 100 (default 30); an unsafe ref is a 422 bad_ref; a private repository needs a token; the 200 carries a weak etag, cache-control private, no-cache and vary authorization, cookie, and a repeat sending If-None-Match gets 304 with no body until the ref
Parameters

owner path string required
name path string required
ref query string
limit query integer

200 Done
304 Done
default An error: { error, message }; `error` is a stable code
owner * name * ref limit
GET /api/v1/repos/{owner}/{name}/commits/{oid} Read one commit (a full or abbreviated id, or a ref) as { oid, parents, author, email, date, subject, body, diff: { files, additions, deletions } }; a private repository needs a token
Parameters

owner path string required
name path string required
oid path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * oid *
GET /api/v1/repos/{owner}/{name}/commits/{oid}/check The default branch's check of a full 40-hex commit id, never cached: { commit, checkedCommit, state, runId, summary, finishedAt }; state is ok, failed, pending, superseded or none; 404 for a short id, an unknown commit or a repository you cannot read
Parameters

owner path string required
name path string required
oid path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * oid *
GET /api/v1/repos/{owner}/{name}/contents Read the tree or a file at `ref` (default: the default branch); no `path` or a directory answers { type: "dir", ref, path, entries }, a file answers { type: "file", ref, path, size, encoding: "utf-8" | "base64", content }, a file over 5 MB is a 413 { type: "file", tooLarge: true, size }; a private repository needs a token
Parameters

owner path string required
name path string required
path query string
ref query string

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * path ref
GET /api/v1/repos/{owner}/{name}/contents/{path} Read a path at `ref` (default: the default branch): a directory answers { type: dir, ref, path, entries }, a file { type: file, ref, path, size, encoding, content } (utf-8, or base64 for binary); a file over 5 MB answers 413 { type: file, tooLarge, size }; 404 for an unsafe ref or path or one that is missing
Parameters

owner path string required
name path string required
path path string required
ref query string

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * path * ref
POST /api/v1/repos/{owner}/{name}/origin-hook The origin of a mirror saying a pull moved: a webhook body signed `x-forge-signature-256: sha256=<hmac>` with the secret this forge derived for the mirror; it only names a pull, which is then read again from the origin. Answers 200 { ok }, and 404 for any refusal
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * JSON body {}
GET /api/v1/repos/{owner}/{name}/tags List a repository's tags, newest first; answers { items: [{ name, oid, commit }], next_cursor }; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422
Parameters

owner path string required
name path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * limit cursor

runs 6

GET /api/v1/repos/{owner}/{name}/decisions Page through the decision ledger as the caller may see it, newest first; `kind` is next, land, retry or guard; `limit` 1 to 100 (default 30), `cursor` is the next_cursor of the page before; answers { decisions, week, next_cursor }; a bad limit or cursor is a 422
Parameters

owner path string required
name path string required
kind query string
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * kind limit cursor
GET /api/v1/repos/{owner}/{name}/events Page through a repository's events as the caller may see them, newest first: {items, next_cursor}; limit 1 to 200 (default 50), cursor from next_cursor, kind keeps one event kind (e.g. repo.settings_updated); a bad limit, kind or cursor is a 422
Parameters

owner path string required
name path string required
kind query string
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * kind limit cursor
GET /api/v1/repos/{owner}/{name}/flow Read how work moves through a repository: { open, live }, where open lists each open issue (and merged ones production has not yet served) as { number, title, stage, since, stalled, unblock, pull } and live lists what went live in the last 24 hours, newest first, the same with liveAt; sealed rows only for those who may see them
Parameters

owner path string required
name path string required

200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (no such repository, or it is not readable by the caller)
owner * name *
GET /api/v1/repos/{owner}/{name}/runs List a repository's runs, newest first: { items, next_cursor }; kind deploy or agent, state queued, running, ok, failed or cancelled (another is a 422), env an environment name, limit 1 to 200 (default 50), cursor a run id; each row carries `shown`, the state worked out from what the run did; a stranger's runs carry no cost, turns, agent session or node; the answer carries a weak ETag (cache-contr
Parameters

owner path string required
name path string required
kind query string
state query enum(open, closed, all)
env query string
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))
owner * name * kind state env limit cursor
GET /api/v1/repos/{owner}/{name}/runs/{id} Read one run as this reader may see it, with `carries`, the merged pulls a finished production deploy carries
Parameters

owner path string required
name path string required
id path string required

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * id *
GET /api/v1/repos/{owner}/{name}/runs/{id}/log Read a run's log as text/plain, one line per line; follow=1 or Accept: text/event-stream tails it live as server-sent events (line, then done); 404 when the log is hidden
Parameters

owner path string required
name path string required
id path string required
follow query string

200 Done
default An error: { error, message }; `error` is a stable code
owner * name * id * follow

tokens 2

POST /api/v1/sessions Sign in with a username and password: answers 201 with the account { id, username, displayName, isAdmin, commitEmail } and sets the HttpOnly forge_session cookie; refused from another origin with 403 forbidden
Body

username string
password string

201 Done
default An error: { error, message }; `error` is a stable code. Refusals: `unauthorized` (401, the username or password is wrong); `too_many_attempts` (429, past the sign-in windows; retry-after says when); `too_large` (413, the body is over the limit for a stranger's)
JSON body {}
DELETE /api/v1/sessions Sign out the session in the forge_session cookie: answers 200 with {} and clears the cookie; refused from another origin with 403 forbidden
200 Done
default An error: { error, message }; `error` is a stable code
JSON body {}

user 4

GET /api/v1/passport/health The forge's public health, for a caller holding a passport (`Authorization: Passport <token>`, audience `forge`, scope `health:read`) rather than a token; answers the same body as the anonymous health, uncached
200 Done
default An error: { error, message }; `error` is a stable code. Refusals: `unauthorized` (the passport is missing, malformed, expired, or not for this audience and scope (always 401))
POST /api/v1/users Sign up: while the forge takes requests (signup `request`) answers 202 { state: 'waiting', username, message } and the account waits for an admin to allow it; otherwise answers 201 with the new account { id, username, displayName, isAdmin, commitEmail }, never the admin; `email` is optional; `invite` is an invite link's token, `turnstile_token` the human check when the forge asks for one; refused
Body

username string
email string
password string
invite string
note string
from string
turnstile_token string

201 Done
default An error: { error, message }; `error` is a stable code. Refusals: `rate_limited` (429, too many sign-ups; retry-after says when); `too_large` (413, the body is over the limit for a stranger's); `signup_closed` (403, this forge makes no new accounts (or the invite is not one)); `forbidden` (403, the name is not one this edge allows); `passkey_required` (422, this forge signs up with a passkey on th
JSON body {}
GET /api/v1/users/{username} Read one person's public profile; 404 when they do not exist or hid themselves from the caller
Parameters

username path string required

200 Done
default An error: { error, message }; `error` is a stable code
username *
GET /api/v1/users/{username}/repos List the repositories a person owns that the caller may see (private ones only to those with access); answers { items, next_cursor }, paged by `limit` and `cursor`. Carries a weak `ETag` (owner, viewer, page and a marker over the rows the caller may see); a repeat with a matching `If-None-Match` answers 304 with no body until one of them is added, pushed to, renamed, changes visibility or its open
Parameters

username path string required
limit query integer
cursor query string

200 Done
400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)
default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)); `invalid_limit` (limit is not a whole number from 1 to 200 (422)); `invalid_cursor` (cursor is not the next_cursor of a previous page (422))
username * limit cursor

code	string
username	string
email	string
scope	string
name	string
expiresIn	integer

owner	path	string	required
name	path	string	required
limit	query	integer

repos	object[]
issues	object[]
code	object[]
truncated	object
moreCode	boolean
codeSkipped	boolean
note	string, only when q is blank: what to send

version	string
date	string
headline	string
highlights	object[]
pulls	object[]

items	object[]
next_cursor	null

kind	string
columns	object[]
items	object[]

API

admin 2

Body

201 Done

Body

201 Done

apps 5

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

Fields

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository or app, or not the caller's to read); `invalid_limit` (422: limit is not a whole number from 1 to 100)

Parameters

200 Done

builds 4

Parameters

200 Done

Fields

304 Done

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: no such repository, or it is not readable)

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

contract 2

308 Done

default An error: { error, message }; `error` is a stable code

200 Done

default An error: { error, message }; `error` is a stable code

crew 4

Parameters

200 Done

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (no such agent, or not yours to see)

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

Fields

default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (q is empty, over 500 characters, or does not parse; the reason is the message (422)); `invalid_sort` (sort is not a column of the kind (422))

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

feed 3

Parameters

200 Done

304 Done

400 page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)

default An error: { error, message }; `error` is a stable code. Refusals: `invalid_query` (page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400))

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

Fields

default An error: { error, message }; `error` is a stable code. Refusals: `invalid_kind` (kind is not all, repos, issues or code (422)); `invalid_limit` (limit is not a whole number from 1 to 100 (422))

forges 9

200 Done

default An error: { error, message }; `error` is a stable code

200 Done

default An error: { error, message }; `error` is a stable code. Refusals: `not_found` (404: this forge was not spawned)

200 Done

default An error: { error, message }; `error` is a stable code

200 Done

default An error: { error, message }; `error` is a stable code

Parameters

200 Done

default An error: { error, message }; `error` is a stable code

Parameters