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.
Endpoints
Section titled “Endpoints”| Method | Path | Purpose |
|---|---|---|
GET | /health | Liveness check. Returns 200 + { status: 'ok', version }. |
GET | /ready | Readiness check. Returns { status: 'ready', version }. |
POST | /api/proxy | HTTP upstream proxy. SSRF-guarded, body normalisation, auth signing. |
POST | /api/import/fetch | Fetch a public import artifact by URL (no custom headers/auth; private networks always refused). |
POST | /api/grpc | gRPC unary + streaming via Connect protocol. |
POST | /api/grpc/reflection | gRPC reflection requests. |
POST | /api/grpc-web | gRPC-Web unary + server streaming; streams NDJSON events back. |
POST | /api/mcp | MCP client proxy (streamable HTTP; the HTTP-SSE transport is desktop-only). |
POST | /api/mcp/terminate | End an MCP session: sends DELETE with Mcp-Session-Id to the server (same SSRF guard as /api/mcp). |
POST | /api/telemetry/error | Scrubbed renderer error reports (opt-out). Public — no token required. |
GET | /api/feature-flags | Protocol kill-switch flags. Public — no token required. |
POST | /api/ws-ticket | Mint a short-lived ticket for the WebSocket proxy. |
GET | /api/ws?ticket=<id> | WebSocket proxy endpoint (single-use ticket, 30 s expiry). |
Authentication
Section titled “Authentication”Production requires one of:
X-Restura-Proxy-Token: <WORKER_PROXY_TOKEN>(orAuthorization: Bearer <WORKER_PROXY_TOKEN>) on each request, or- A valid signed
Cf-Access-Jwt-Assertion(whenREQUIRE_CF_ACCESS=true, withCF_ACCESS_TEAM_DOMAINandCF_ACCESS_AUDset).
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.
| Status | When |
|---|---|
401 | Token or Cloudflare Access assertion missing or wrong. |
403 | Dev bypass only: foreign Origin. |
415 | POST /api/* without a JSON Content-Type. |
503 | No auth mode configured (or REQUIRE_CF_ACCESS=true without its team domain / AUD). |
Rate limiting
Section titled “Rate limiting”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.
Related
Section titled “Related”- Architecture / Shared protocol layer — how these endpoints map to the protocol cores.
- Security model — auth gate, SSRF guard.