Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.worldflux.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Source of truth

The cloud control plane is a FastAPI service. Its OpenAPI document is the canonical reference; this page lists only the BFF routes the dashboard calls. 
GET /openapi.json
GET /docs
To regenerate the dashboard’s TypeScript client from that document: 
cd web
npm run generate:api

​
Traffic model

The CLI talks to FastAPI directly with Authorization: Bearer <api-key>. The dashboard sits behind Supabase auth and routes its calls through the Next.js BFF (/api/cloud/*), which adds the workspace context and forwards to FastAPI. /openapi.json remains the source of truth for generated clients.

​
BFF routes

These are the dashboard’s own routes. Most are thin proxies that add auth and forward the body to FastAPI.
RouteFastAPI targetUsed by
GET /api/cloud/me/api/meProfile panel
PATCH /api/cloud/me/api/meProfile opt-ins
POST /api/cloud/me/api/me/...DSAR actions (export, delete, restrict)
GET /api/cloud/workspaces/api/workspacesWorkspace switcher
POST /api/cloud/workspaces/api/workspacesWorkspace creation
GET /api/cloud/projects/api/projectsProject list
POST /api/cloud/projects/api/projectsProject creation
GET /api/cloud/runs/api/runsRecent runs table
POST /api/cloud/api-keys/api/api-keysAPI key issuance (one-time secret)
POST /api/cloud/shares/api/sharesCreate / revoke public share
POST /api/cloud/billing/checkout/api/billing/checkoutStripe Checkout session
POST /api/cloud/billing/portal/api/billing/portalStripe Customer Portal
POST /api/cloud/sample-run/api/runs (synthetic)Onboarding “upload sample run”
Plus auth routes used by the dashboard’s session flow:
RoutePurpose
POST /api/auth/loginSupabase email/password sign-in
POST /api/auth/signupSupabase email/password sign-up
POST /api/auth/logoutSupabase sign-out
POST /api/auth/reset-passwordSupabase reset email request
GET /api/auth/sessionCurrent session check
And public-share routes:
RoutePurpose
GET /api/public/r/[token]Resolve a public share token to a run snapshot

​
Auth header

All /api/cloud/* calls expect a Supabase session cookie when called from the dashboard. The CLI does not call these BFF routes; it sends Authorization: Bearer <wbx_…> directly to FastAPI.

​
Error shape

The BFF normalizes failures into one shape: 
{
  "error": {
    "code": "login_required",
    "message": "Please log in again."
  }
}
code is stable. Common values seen by the dashboard:
CodeWhen
login_requiredSession missing or expired. The dashboard redirects to /login.
validation_errorBody shape mismatch. details carries the offending field path.
quota_exceededWorkspace plan cap hit. The Billing panel surfaces an upgrade CTA.
not_foundResource id does not exist or is invisible to this caller.
unsupported_actionMethod not allowed (e.g. POST /api/cloud/runs without the e2e fixture flag).

​
E2E fixtures

When WORLDFLUX_E2E_FIXTURES=1 is set, the BFF returns deterministic in-memory data instead of proxying to FastAPI. This is what Playwright tests use. 
if (e2eFixturesEnabled()) {
  return NextResponse.json(listE2ERuns());
}
/api/e2e/cli-sync is the synthetic endpoint the test suite hits to seed runs.