WorldFlux Docs - BYO-compute physical-AI evaluation evidence

Source of truth

The cloud control plane is a FastAPI service. Its OpenAPI document is the canonical reference; this page summarizes the direct FastAPI surface and 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 uses two BFF layers: named /api/cloud/* routes for higher-level dashboard actions, and a guarded catch-all /api/[...path] proxy for a narrow allowlist of Cloud read/sync routes. /openapi.json remains the source of truth for generated clients.

FastAPI route families

Family	Routes
System	`/`, `/healthz`, `/health`, `/health/db`, `/health/r2`
Status	`GET /api/status`, `GET /api/status/operational`
Workspaces	`/api/workspaces`, `/api/workspaces/{workspace_id}`, invitations, transfer ownership
Projects	`/api/projects`, `/api/projects/{project_id}`
Sync	`POST /api/sync/runs`, `GET /api/sync/ledger-head`, `POST /api/sync/ledger-head`, artifact initiate/commit/abort
Runs	`/api/runs`, `/api/runs/{run_id}`, manifest, metrics, log, signature, compliance mapping, artifact download, delete
API keys	`/api/api-keys`, rotate, revoke
Shares	`/api/shares`, revoke, `/api/public/shares/{token}`
Billing	checkout, portal, webhook
Usage	reserve, commit, revert
Profile / DSAR	`/api/me`, object, restrict, export, delete, cancel delete
Claims	`/api/claims`, `/api/claims/{claim_id}`
Museum	`/api/museum`
Audit logs	`/api/audit/logs`

Machine-checked Cloud route list:

GET /
GET /api/api-keys
POST /api/api-keys
DELETE /api/api-keys/{api_key_id}
POST /api/api-keys/{api_key_id}/rotate
GET /api/artifacts/{artifact_id}
GET /api/audit/logs
POST /api/billing/checkout
POST /api/billing/portal
POST /api/billing/webhook
GET /api/claims
GET /api/claims/{claim_id}
GET /api/me
PATCH /api/me
POST /api/me/delete
POST /api/me/delete/cancel
GET /api/me/export
POST /api/me/object
POST /api/me/restrict
GET /api/museum
GET /api/projects
POST /api/projects
DELETE /api/projects/{project_id}
GET /api/projects/{project_id}
PATCH /api/projects/{project_id}
DELETE /api/projects/{project_id}/staging-e2e-tree
POST /api/projects/{project_id}/staging-retention-proof
GET /api/public/shares/{token}
GET /api/runs
DELETE /api/runs/{run_id}
GET /api/runs/{run_id}
POST /api/runs/{run_id}/evidence-package
GET /api/runs/{run_id}/log
GET /api/runs/{run_id}/manifest
GET /api/runs/{run_id}/metrics
GET /api/shares
POST /api/shares
POST /api/shares/{share_id}/reliability-consent
DELETE /api/shares/{share_id}/reliability-consent/{consent_id}
GET /api/shares/{share_id}/reliability-consent/{consent_id}/export
POST /api/shares/{share_id}/reliability-consent/{consent_id}/revoke
POST /api/shares/{share_id}/revoke
GET /api/status
GET /api/status/operational
POST /api/sync/artifacts/abort
POST /api/sync/artifacts/commit
POST /api/sync/artifacts/initiate
GET /api/sync/ledger-head
POST /api/sync/ledger-head
POST /api/sync/runs
POST /api/usage/reserve
POST /api/usage/commit
POST /api/usage/revert
GET /api/workspaces
POST /api/workspaces
DELETE /api/workspaces/{workspace_id}
GET /api/workspaces/{workspace_id}
PATCH /api/workspaces/{workspace_id}
GET /api/workspaces/{workspace_id}/invitations
POST /api/workspaces/{workspace_id}/invitations
PATCH /api/workspaces/{workspace_id}/transfer-ownership
GET /health
GET /health/db
GET /health/r2
GET /healthz

BFF routes

These are the dashboard’s own routes. Most are thin proxies that add auth and forward the body to FastAPI.

Route	FastAPI target	Used by
`GET /api/cloud/me`	`/api/me`	Profile panel
`PATCH /api/cloud/me`	`/api/me`	Profile opt-ins
`POST /api/cloud/me`	`/api/me/...`	DSAR actions (export, delete, restrict)
`GET /api/cloud/workspaces`	`/api/workspaces`	Workspace switcher
`POST /api/cloud/workspaces`	`/api/workspaces`	Workspace creation
`GET /api/cloud/projects`	`/api/projects`	Project list
`POST /api/cloud/projects`	`/api/projects`	Project creation
`GET /api/cloud/runs`	`/api/runs`	Recent runs table
`POST /api/cloud/api-keys`	`/api/api-keys`	API key issuance (one-time secret)
`POST /api/cloud/shares`	`/api/shares`	Create / revoke public share
`POST /api/cloud/billing/checkout`	`/api/billing/checkout`	Stripe Checkout session
`POST /api/cloud/billing/portal`	`/api/billing/portal`	Stripe Customer Portal
`POST /api/cloud/sample-run`	`/api/runs` (synthetic)	Onboarding “upload sample run”
`POST /api/workspace/selection`	local selection state	Workspace switcher

The catch-all proxy /api/[...path] is intentionally allowlisted. It forwards only:

GET /health
GET /api/status
GET /api/runs, GET /api/runs/{run_id}, and run manifest/metrics/log/signature/compliance mapping reads
GET /api/artifacts/{artifact_id}
GET /api/claims, GET /api/claims/{claim_id}
GET /api/museum
workspace/project list and creation
API-key creation
share list/create/revoke
sync run create and artifact initiate/commit/abort

Unsupported methods, paths, or query parameters are rejected before Cloud is called. Machine-checked BFF proxy allowlist:

GET /health
GET /api/status
GET /api/runs
GET /api/runs/{id}
GET /api/runs/{id}/{manifest|metrics|log|signature|compliance_mapping}
GET /api/artifacts/{id}
GET /api/claims
GET /api/claims/{id}
GET /api/museum
GET /api/workspaces
POST /api/workspaces
GET /api/projects
POST /api/projects
POST /api/api-keys
GET /api/shares
POST /api/shares
POST /api/shares/{uuid}/revoke
POST /api/sync/runs
POST /api/sync/artifacts/{initiate|commit|abort}

Plus auth routes used by the dashboard’s session flow:

Route	Purpose
`POST /api/auth/login`	Supabase email/password sign-in
`POST /api/auth/signup`	Supabase email/password sign-up
`POST /api/auth/logout`	Supabase sign-out
`POST /api/auth/reset-password`	Supabase reset email request
`POST /api/auth/session`	Current session check

Dashboard pages also cover forgot-password, reset-password, and verify-email flows. Public-share routes are separate from authenticated dashboard routes:

Route	Purpose
`GET /api/public/r/[token]`	Resolve a public share token to a run snapshot
`GET /api/public/vla-leaderboard`	Return public VLA leaderboard snapshots

Public share reads use stable public-safe states:

State	HTTP status	Code	Cache
Active share	200	n/a	`private, no-store`
Token not found or token mismatch	404	`share_not_found`	`no-store`
Revoked	410	`share_revoked`	`no-store`
Expired	410	`share_expired`	`no-store`
Missing password	401	`share_password_required`	`no-store`
Wrong password	401	`share_wrong_password`	`no-store`
Password locked	429	`share_password_locked`	`no-store` + rate-limit headers
Read rate limited	429	`share_rate_limited`	`no-store` + rate-limit headers
Evidence verification failure	409	`evidence_unverified`	`no-store`
Artifact filtered or unavailable	409	`artifact_filtered`	`no-store`
Public payload policy rejected	409	`public_payload_policy_rejected`	`no-store`

Web clients must render public-only unavailable states for these codes and must not fall back to dashboard controls or internal identifiers. Machine-checked named BFF route list:

DELETE /api/[...path]
GET /api/[...path]
PATCH /api/[...path]
POST /api/[...path]
PUT /api/[...path]
POST /api/auth/login
POST /api/auth/logout
POST /api/auth/reset-password
POST /api/auth/session
POST /api/auth/signup
DELETE /api/cloud/api-keys
POST /api/cloud/api-keys
POST /api/cloud/billing/checkout
POST /api/cloud/billing/portal
GET /api/cloud/me
PATCH /api/cloud/me
POST /api/cloud/me
DELETE /api/cloud/projects
GET /api/cloud/projects
POST /api/cloud/projects
POST /api/cloud/projects/[projectId]/staging-retention-proof
GET /api/cloud/runs
POST /api/cloud/runs
POST /api/cloud/sample-run
GET /api/cloud/shares
POST /api/cloud/shares
DELETE /api/cloud/workspaces
GET /api/cloud/workspaces
POST /api/cloud/workspaces
POST /api/e2e/cli-sync
GET /api/public/r/[token]
GET /api/public/vla-leaderboard
POST /api/workspace/selection

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 <wfx_…> 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:

Code	When
`login_required`	Session missing or expired. The dashboard redirects to `/login`.
`validation_error`	Body shape mismatch. `details` carries the offending field path.
`quota_exceeded`	Workspace plan cap hit. The Billing panel surfaces an upgrade CTA.
`not_found`	Resource id does not exist or is invisible to this caller.
`unsupported_action`	Method not allowed (e.g. `POST /api/cloud/runs` without the e2e fixture flag).

E2E fixtures

When WORLDFLUX_WEB_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.

​Source of truth

​Traffic model

​FastAPI route families

​BFF routes

​Auth header

​Error shape

​E2E fixtures