HTTP API reference

Base URL and response conventions

The public website uses https://forkd.fun. Application endpoints are rooted at /api and return JSON except the Markdown brief download. Send JSON request bodies with Content-Type: application/json. API responses are marked no-store.

Read endpoints can return 503 for unexpected data failures. Mutations fail when storage is unavailable; the current generic mutation error handler returns 400 for several validation and configuration failures. Do not infer authentication or storage readiness from a status code alone—read the error body and availability flags.

GET https://forkd.fun/api/catalogue
GET https://forkd.fun/api/catalogue/percolator
GET https://forkd.fun/api/catalogue/percolator/brief

GET /api/catalogue

Query parameters: q searches name, owner/repository, proposed name, description, category and language; category matches an exact returned category; gate accepts all, voted, ready or review; sort accepts votes, stars or name; page is a positive page number.

The response contains items, total, page, pageSize, pages, totalRepositories, categories, reviewed, verifiedAt, authenticated and storageUnavailable. Pages contain at most 12 items. The ready filter means a non-archived candidate with a permissive detected license; it does not mean deployment-ready.

Each item includes its research fields, votes and voted, plus votesAvailable. If storageUnavailable is true or votesAvailable is false, vote fields are unavailable defaults rather than observed counts. A single-candidate read returns the candidate directly; its /brief variant returns an attachment with text/markdown content type.

GET /api/catalogue?q=uniswap&sort=stars&page=1
GET /api/catalogue?gate=ready&sort=name
GET /api/catalogue/<candidate-id>/brief

GET /api/overview

The overview returns requests, jobs, events, ledger, stats, configured, catalogueCount, user and storageUnavailable. The configured object exposes public repository information and service configuration flags, not secret values.

When storage is unavailable, the response contains empty collections and default statistics alongside storageUnavailable: true. These values must not be displayed as live observed treasury balances or completed-job counts. GET /api/requests/<request-id> reads a saved request and requires working storage.

Read build events

GET /api/build-events returns the latest 50 public events. GET /api/jobs/<job-id>/events?after=<sequence> returns up to 100 events after that job’s sequence number in ascending order. Both return an events collection and storageUnavailable.

Events expose jobId, sequence, kind, tool, file, message, model, commitUrl, createdAt and project. They contain sanitized activity only. Poll the job-specific route with its last received sequence and deduplicate by jobId plus sequence.

GET /api/build-events
GET /api/jobs/<job-id>/events?after=12

Authenticated account actions

POST /api/catalogue/<candidate-id>/vote accepts {"voted":true} or {"voted":false}. A successful response returns id, votes and voted. Missing account authentication produces a signInRequired response when storage is present.

POST /api/requests creates a source-checked request and returns 201. Required fields are name, ticker, repo, description and acceptedTerms:true. Optional category defaults to Infrastructure and accepts Infrastructure, Perpetuals, DeFi, Wallets, Developer tools or NFTs.

POST /api/requests/<request-id>/vote toggles that request’s vote. POST /api/requests/<request-id>/analyze prepares its source plan. POST /api/requests/<request-id>/build reserves credit and dispatches execution. Review and build actions require the requesting account. User mutations check the Origin header when supplied.

{
  "name": "Percolator research port",
  "ticker": "PERC",
  "repo": "https://github.com/aeyakovenko/percolator",
  "description": "Prepare reference vectors and document the EVM adapter boundaries.",
  "category": "Perpetuals",
  "acceptedTerms": true
}

Funding receipt and settlement endpoints

POST /api/funding/receipt requires an authenticated account and a JSON body with requestId plus tx, a 0x-prefixed 32-byte transaction hash. The server verifies the chain receipt against registered router configuration before adding eligible ledger entries.

POST /api/admin/funding-credit requires the separate operator bearer credential. Its body contains ledgerId, settlementRef and usdMicros. The ledger entry must be a verified build-fee receipt. settlementRef is 8–200 characters and usdMicros is a positive integer no greater than 100,000,000,000. Reused settlement records are not credited twice.

These are accounting operations, not token swaps or provider top-up APIs. Never place an operator credential in frontend requests or public examples.

Authenticated runner callbacks

POST /api/jobs/<job-id>/events requires BUILD_RUNNER_SECRET as a bearer credential. The body includes sequence (1–10,000), kind and message, with optional tool, file, model and commitUrl. Supported kinds are phase, tool_start, file_changed, command_result, publication, budget, complete and error.

POST /api/jobs/<job-id>/complete uses the same service credential. Its body has status (review or failed), a nonnegative integer costMicros, summary and optional HTTPS artifact URL. Reported cost cannot exceed the reserved amount. Successful duplicate callbacks are acknowledged without settling twice.

Separate runner API

The runner exposes authenticated POST /jobs with an Idempotency-Key matching jobId. Its bounded payload is produced by the web dispatcher. A valid job returns 202; an existing ID with a changed payload returns 409.

GET /artifacts/<job-id> exposes the sanitized artifact for a completed job on the configured runner origin. Anyone with that URL can read its public contents. No general user API token issuance, WebSocket stream or automated deployment endpoint is included in this release.