The API reference

/api renders the forge's OpenAPI document (src/contract/openapi.ts) as a page: operations grouped by area (the first word after /api/v1), a search box (?q=, a plain GET form), and for each operation a fold with its parameters, body fields and replies. It is server-rendered; the folds are <details>. Nothing is loaded from elsewhere, and the one script (API_TRY_JS in src/web/api_reference.ts) is on this page only.

Try it sends the request as you (your session cookie) or as a token you paste, and shows the status, the time, the Server-Timing header and the body. A GET with no path parameter also works with no script: the form is a plain GET to the endpoint. A request that is not a GET asks to confirm first.

An app's API tab. An app whose production environment serves /openapi.json gets an API tab next to Runs, at /:owner/:name/api, rendered by the same reading (src/contract/reference.ts). The forge reads the file over loopback (bounded to 512 KB and 1.5 s, kept only when it is a JSON object with paths) and remembers it for a minute (src/apps/api_spec.ts); the tab appears once the header has seen it. Try it is not offered on an app's operations: they live on another origin.

In the terminal: API in the command palette lists the same operations; / narrows; Enter on a GET with no path parameter runs it as the person at the terminal and shows the status, time, Server-Timing and body.

/api answers no_route in JSON to a caller whose Accept prefers JSON, as the rest of /api does.

A list the contract gives a cursor pages by it: ?page= or ?offset= on one is a 400 invalid_query ("This list pages by cursor: pass next_cursor as ?cursor="), answered by one guard in src/http/cursor_lists.ts before any handler runs, and named in the document as the route's 400.

The root, GET /api/v1, names the OpenAPI, MCP, OAuth and llms.txt URLs with no account: the API root.

Roles. Every operation in the document carries x-role: anonymous (no account at all), member (any signed-in account; the summary adds a token scope or a repository right where one applies, or says the route takes a browser session or the password and refuses a bearer token, as the token routes do) or admin (a site admin only). It is a required field of each route row (role in src/contract/openapi/shared.ts's Route), so a new route cannot leave it out; test/openapi-drift.test.ts pins the routes easy to misread, and the same test fails when a route is described but not routed or routed but not described.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs