Documentation

HTTP API

Understand the public, browser, CLI, and automation surfaces that exist today.

Upstream exposes versioned backend APIs through the upstream.codes same-origin proxy. The OpenAPI 3.1 document is the machine-readable reference for the currently published surface.

Endpoint families

https://upstream.codes/api/forge/public/...
https://upstream.codes/api/forge/developer/...

Public endpoints cover namespace and repository discovery, source browsing, Change Requests, Issues, forks, and Actions reads. Some contributor mutations require a signed-in browser session.

Developer endpoints cover the signed-in dashboard, repository index, notifications, preferences, Git credentials, API tokens, SSH keys, CLI sessions, and GitHub Sync.

Current boundaries

SurfaceAuthenticationIntended use
Public forge APIAnonymous reads; signed-in session for contributor mutationsPublic namespaces, repositories, source, Change Requests, Issues, forks, and Actions
Developer browser APIUpstream session cookie plus same-origin checksDashboard, account settings, repository management, credentials, and GitHub Sync
CLI APIBrowser-approved CLI sessionTerminal repository, Change Request, workspace, and ruleset commands
External checks APIWorkspace API token with upstream.checks.writeCI and agent check reports

There is not yet a general-purpose workspace bearer token for every forge mutation. Use the CLI for terminal automation, the public API for published data, and the external-checks endpoint for CI results.

Response envelopes

Successful responses use:

{ "data": { "...": "..." } }

Errors use a matching HTTP status and a stable body:

{
  "error": {
    "code": "REPOSITORY_NOT_FOUND",
    "message": "Repository not found."
  }
}

Some errors add a recovery hint or documentation path. Clients should branch on the code and status, not parse the message.

Discovery