Skip to content

API reference

The Restura server exposes these HTTP endpoints. The same Hono app runs in the Cloudflare Worker (api.restura.dev) and in the Node / Docker self-hosted process.

MethodPathPurpose
GET/healthLiveness check. Returns 200 + { status: 'ok', version }.
GET/readyReadiness check. Returns { status: 'ready', version }.
POST/api/proxyHTTP upstream proxy. SSRF-guarded, body normalisation, auth signing.
POST/api/import/fetchFetch a public import artifact by URL (no custom headers/auth; private networks always refused).
POST/api/grpcgRPC unary + streaming via Connect protocol.
POST/api/grpc/reflectiongRPC reflection requests.
POST/api/grpc-webgRPC-Web unary + server streaming; streams NDJSON events back.
POST/api/mcpMCP client proxy (streamable HTTP; the HTTP-SSE transport is desktop-only).
POST/api/mcp/terminateEnd an MCP session: sends DELETE with Mcp-Session-Id to the server (same SSRF guard as /api/mcp).
POST/api/telemetry/errorScrubbed renderer error reports (opt-out). Public — no token required.
GET/api/feature-flagsProtocol kill-switch flags. Public — no token required.
POST/api/ws-ticketMint a short-lived ticket for the WebSocket proxy.
GET/api/ws?ticket=<id>WebSocket proxy endpoint (single-use ticket, 30 s expiry).

Production requires one of:

  • X-Restura-Proxy-Token: <WORKER_PROXY_TOKEN> (or Authorization: Bearer <WORKER_PROXY_TOKEN>) on each request, or
  • A valid signed Cf-Access-Jwt-Assertion (when REQUIRE_CF_ACCESS=true, with CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD set).

With neither configured, /api/* fails closed with 503. /health, /ready, /api/feature-flags, and /api/telemetry/error need no token.

Local dev bypasses auth only when ENVIRONMENT=development and either Miniflare is detected or DEV_BYPASS_AUTH=true is set in .dev.vars. In bypass mode a browser request whose Origin is neither the server’s own origin nor listed in ALLOWED_ORIGIN is refused with 403 {"error":"Origin not allowed"}.

Every POST /api/* must send Content-Type: application/json (parameters such as ; charset=utf-8 are fine); anything else gets 415 {"error":"Content-Type must be application/json"}. This check runs before auth, so it also applies to the public endpoints and in bypass mode — it stops a cross-site page from driving the proxy with a preflight-free text/plain or form POST.

StatusWhen
401Token or Cloudflare Access assertion missing or wrong.
403Dev bypass only: foreign Origin.
415POST /api/* without a JSON Content-Type.
503No auth mode configured (or REQUIRE_CF_ACCESS=true without its team domain / AUD).

Cloudflare deployment: rate-limiting binding in the Worker.

Self-hosted: per-replica in-memory token bucket. For multi-replica setups, put a rate limiter in your reverse proxy.