API reference

Forge provides a JSON API and a stateless MCP endpoint. Public discovery and examples require no account. Private runs require a workspace session or bearer token.

Discover

• GET /api/health: service status and queue depth.

• GET /api/catalog: examples, source text, targets and recipes.

• GET /openapi.json: API contract.

• GET /.well-known/api-catalog: API discovery linkset.

• GET /.well-known/mcp/server-card.json: MCP transport and tools.

Run an example

curl -c cookies.txt https://forge.keff.uk/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"example":"axpy","target":"arm-n1","recipe":"cleanup"}'

The response is HTTP 202 with a run id and queued status. Keep the session cookie to inspect the private report. Poll GET /api/runs/{id} while its status is queued or running. Stop polling once it is completed, failed, timeout or interrupted.

Private source

Create and sign in to a workspace in the browser. In Runs, create an API token. Send Authorization: Bearer with that token. POST /api/runs accepts source, target, recipe and an optional title. Inputs are MLIR text; requests cannot provide executable commands.

Artifacts and sharing

GET /api/runs/{id} returns the complete report to its owner. POST /api/runs/{id}/share with confirm_public=true publishes the report. GET /api/shared/{token} reads an explicitly published report. DELETE /api/runs/{id} removes the owner's run and revokes its shared URL.

MCP

POST /mcp supports initialize, tools/list and tools/call over Streamable HTTP. Available tools are list_examples, run_example and get_report. Pass a bearer token to access your private reports. The run_example tool returns a queued id; fetch it with get_report until terminal status.

Errors

400 means invalid input, 401 means sign-in is required, 403 means a rejected origin, 404 means absent or inaccessible data, 413 means oversized input, and 429 means an admission limit. Compiler errors are retained in a terminal run report. A failed pipeline is never represented as a successful comparison.