API reference

The PWFabric API is a REST API served at:

Production: https://api.phiwebs.com
Staging: https://api-staging.phiwebs.com
Local dev: http://localhost:4000

Authentication

All authenticated endpoints require a JWT Bearer token in the Authorization header. Obtain a token via POST /api/auth/login or the OAuth2 PKCE flow.

Authorization: Bearer <your-jwt-token>
X-World-ID: your-world-id

Authentication endpoints

User authentication and token management.

Method	Path	Description
`POST`	`/api/auth/register`	Register a new user account. Body: `{ email, password, name }`. Response: `{ data: { user, token, refreshToken } }`.
`POST`	`/api/auth/login`	Authenticate with email and password. Body: `{ email, password }`.
`POST`	`/api/auth/refresh`	Refresh an expired access token. Body: `{ refreshToken }`.
`POST`	`/api/auth/oauth/callback`	Handle OAuth2 PKCE callback. Body: `{ code, state, codeVerifier, provider }`.
`GET`	`/api/auth/me`	Get the currently authenticated user profile. Auth required.

Surface endpoints

Surface CRUD and lifecycle operations.

Method	Path	Description
`GET`	`/api/surfaces`	List all Surfaces in the World.
`POST`	`/api/surfaces`	Create a new Surface. Body: `{ name, slug, description?, blocks? }`.
`GET`	`/api/surfaces/by-slug/:worldSlug/:surfaceSlug`	Look up a published Surface by its slug.
`GET`	`/api/surfaces/:id`	Get a Surface by ID.
`DELETE`	`/api/surfaces/:id`	Archive a Surface (revisions preserved).
`GET`	`/api/surfaces/:id/draft`	Get the live draft.
`PUT`	`/api/surfaces/:id/draft`	Save changes to the draft.
`POST`	`/api/surfaces/:id/publish`	Publish the current draft as a new revision. Body: `{ version, revision? }`.
`POST`	`/api/surfaces/:id/unpublish`	Unpublish the live revision.
`GET`	`/api/surfaces/:id/preview`	Render a preview of the current draft.
`GET`	`/api/surfaces/:id/published`	Get the currently-published revision.
`GET`	`/api/surfaces/:id/published/:version`	Get a specific published version.
`GET`	`/api/surfaces/:id/revisions`	List all revisions.
`POST`	`/api/surfaces/:id/revisions`	Create a new revision (snapshot the current draft).
`POST`	`/api/surfaces/:id/revisions/:rev/restore`	Restore a previous revision (rollback).
`GET`	`/api/surfaces/:id/revisions/:from/diff/:to`	Receipt diff between two revisions.
`GET`	`/api/surfaces/:id/publish/suggest-version`	Suggest the next semver.
`PATCH`	`/api/surfaces/:id/visibility`	Update the visibility (`private` / `world` / `domain`).

Billing endpoints

Subscription management and payment processing.

Method	Path	Description
`GET`	`/api/billing/overview`	Current plan, usage, invoices, next-bill date.
`GET`	`/api/billing/plans`	List available plans + Φ grants.
`POST`	`/api/billing/checkout`	Create a checkout session for an upgrade.
`POST`	`/api/billing/upgrade`	Apply an immediate plan change (proration handled server-side).
`POST`	`/api/billing/cancel`	Schedule cancellation at end of current period.
`PATCH`	`/api/billing/profile`	Update billing contact, VAT ID, tax country.
`POST`	`/api/billing/3ds-callback`	3DS challenge callback from the PSP.
`POST`	`/api/billing/webhook`	Inbound PSP webhook (signed).

Team endpoints

Team management and member roles (Team / Enterprise plans).

Method	Path	Description
`GET`	`/api/teams`	List all teams for the World.
`GET`	`/api/teams/:id`	Get a team by ID with members.
`POST`	`/api/teams`	Create a new team.
`PATCH`	`/api/teams/:id`	Update team name, slug, or description.
`DELETE`	`/api/teams/:id`	Delete a team.
`POST`	`/api/teams/:id/members`	Add a member to a team with a role.
`PATCH`	`/api/teams/:id/members/:userId`	Update a member role.
`DELETE`	`/api/teams/:id/members/:userId`	Remove a member from a team.

Upload endpoints

File upload and storage management.

Method	Path	Description
`POST`	`/api/uploads`	Multipart upload. Images are auto-processed into 5 variants.
`POST`	`/api/uploads/presign`	Generate a presigned URL for direct client-to-storage upload.
`DELETE`	`/api/uploads/:path`	Delete an uploaded file and all its variants.

AI endpoints

AI-powered surface generation and assistance.

Method	Path	Description
`POST`	`/api/ai/composer/stream`	SSE-streaming PhiCo composer (ADR-100).
`POST`	`/api/ai/complete`	Synchronous completion for short prompts.
`POST`	`/api/ai/embed`	Generate embeddings (used by PhiSo retrieval).
`POST`	`/api/ai/analyze`	Analyze a Surface or block tree.
`GET`	`/api/ai/suggestions/:surfaceId`	List Surface suggestions.
`POST`	`/api/ai/suggestions/:surfaceId/apply/:suggestionId`	Apply a suggestion to the Surface.
`GET`	`/api/ai/metrics`	Per-agent usage for the current day.
`GET`	`/api/ai/usage`	Φ ledger spend per period.
`GET`	`/api/ai/credits/balance`	Remaining Φ balance.
`GET`	`/api/ai/models`	List available models for the current plan.
`GET`	`/api/ai/capabilities`	Resolve AI capability entitlements per plan.
`GET`	`/api/ai/mind`	PhiSo mind summary for the current World.
`GET`	`/api/ai/agents` · `POST /api/ai/agents`	List / create custom agents.
`GET` · `PUT` · `DELETE`	`/api/ai/agents/:id`	Read / update / delete a custom agent.

Audit log endpoints

Activity audit trail (Enterprise plan).

Method	Path	Description
`GET`	`/api/audit`	List audit logs with pagination + filters.
`GET`	`/api/audit/:id`	Get a single audit log entry with before/after diff.
`GET`	`/api/audit/export`	Export audit logs as CSV.
`GET`	`/api/audit/stats`	Aggregated audit statistics.

SSO endpoints

Single Sign-On configuration (Enterprise plan).

Method	Path	Description
`GET`	`/api/sso/configs`	List all SSO configurations.
`POST`	`/api/sso/configs`	Create a new SSO configuration (OIDC or SAML).
`PATCH`	`/api/sso/configs/:id`	Update SSO configuration.
`DELETE`	`/api/sso/configs/:id`	Delete SSO configuration.
`POST`	`/api/sso/configs/:id/enable`	Enable an SSO configuration.
`POST`	`/api/sso/auth/initiate`	Initiate SSO authentication flow (redirects to IdP).

World, blueprint, and capability endpoints

Method	Path	Description
`GET` · `PATCH`	`/api/world`	Read or update the current World profile.
`GET` · `POST`	`/api/worlds`	List Worlds visible to the current user (Enterprise multi-World) / provision a new World.
`GET` · `POST`	`/api/blueprints`	List / create World blueprints (ADR-125).
`GET`	`/api/capabilities`	Resolve capability entitlements for the current World.
`GET` · `POST` · `PATCH` · `DELETE`	`/api/invitations`	World invitation lifecycle.

Marketplace, OAuth, uploads

Method	Path	Description
`GET` · `POST`	`/api/marketplace/artifacts`	List / publish pwpack atoms.
`POST`	`/api/marketplace/payments/intent`	Create a purchase intent.
`GET` · `POST`	`/api/oauth/clients`	List / create partner OAuth client apps.
`GET` · `POST`	`/api/oauth/connections`	List / create OAuth connections to third-party providers.
`POST`	`/api/uploads`	Multipart upload; images auto-process into 5 variants.
`POST`	`/api/uploads/presign`	Presigned URL for direct client → R2 upload.
`DELETE`	`/api/uploads/:path`	Delete an uploaded file + its variants.

Health endpoints

Method	Path	Description
`GET`	`/health`	Check API health. Returns `{ status: "ok", timestamp }`.

OpenAPI schema

A live OpenAPI 3.0 schema is served at /api/meta. Use it with code generators (e.g., openapi-typescript, orval) or import into Postman / Insomnia / Hoppscotch.

curl https://api.phiwebs.com/api/meta > openapi.json

@phimajor-solutions/pwfabric-phico Rate limits & quotas