API reference
The PhiWebs API is a REST API served at:
https://api.phiwebs.com
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-idAuthentication 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. |
App endpoints
An app is the top-level unit: its pages, its records, its visitor sign-in and its appearance, published together. These are the endpoints that address one.
| Method | Path | Description |
|---|---|---|
GET | /api/phico-projects | List the apps in the World. |
POST | /api/phico-projects | Create an app. |
GET | /api/phico-projects/:id | Get one app with its pages and settings. |
PATCH | /api/phico-projects/:id | Update name, slug, settings. |
DELETE | /api/phico-projects/:id | Delete an app. |
POST | /api/phico-projects/:id/publish-explore | Publish: install the assembled app at its public address. |
GET | /api/phico-projects/:id/publish-explore/status | Whether what is live matches the current draft. |
POST | /api/phico-projects/:id/export | Export a pwapp — a ready-to-run bundle for any static host. |
POST | /api/phico-projects/:id/download-pwpack | Download the app’s full source as a pwpack. |
POST | /api/phico-projects/:id/duplicate | Copy the app. |
POST | /api/phico-projects/:id/publish-marketplace | Submit the app as a marketplace listing. Publisher accounts only; not open to other teams today. |
GET · POST | /api/phico-projects/:id/members | Who may work on this app. |
GET | /api/phico-projects/:id/identity/methods | The visitor sign-in methods the app declares. |
Visitors of a published app authenticate against a different base,
/api/app/{worldId}/{appId} — see Visitor sign-in.
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 / shared / listed). |
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 + AI credits. |
POST | /api/checkout/subscribe | Start a subscription on a plan. |
POST | /api/checkout/sessions | Create a checkout session. |
POST | /api/checkout/sessions/:id/pay | Pay a checkout session. |
POST | /api/billing/change-plan | Change plan. An upgrade applies immediately with the remaining period prorated; a downgrade takes effect at the end of the current period. |
POST | /api/billing/cancel | Schedule cancellation at end of current period. |
PATCH | /api/billing/profile | Update billing contact, VAT ID, tax country. |
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 up to 10 MB, video up to 200 MB. |
POST | /api/uploads/presign | Generate a presigned URL for direct client-to-storage upload. |
GET | /api/media | List uploaded media. Add ?w=400 to a media URL for a resized WebP variant, generated on demand. |
AI endpoints
AI-powered surface generation and assistance.
| Method | Path | Description |
|---|---|---|
POST | /api/ai/composer/stream | SSE-streaming PhiCo composer. |
POST | /api/ai/complete | Synchronous completion for short prompts. |
POST | /api/ai/embed | Generate embeddings. |
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. |
GET | /api/ai/capabilities | Resolve AI capability entitlements per plan. |
GET | /api/ai/mind | Mind of PhiCo inspection 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 (Team and Enterprise plans).
| 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 | /api/world/:worldId | Read a World profile; PATCH /:worldId/preferences updates its preferences. |
POST | /api/worlds | Provision a new World. GET /api/worlds/me lists the Worlds you belong to; GET /api/worlds/:slug reads one. |
GET | /api/blueprints | List the World blueprints available to the current World. |
GET | /api/capabilities | Resolve capability entitlements for the current World. |
GET · POST | /api/world/:worldId/invitations | List or send World invitations; POST /:id/revoke withdraws one. |
GET | /api/invitations/:token | Read an invitation from its link; POST /:token/accept or /decline answers it. |
Marketplace, OAuth, uploads
| Method | Path | Description |
|---|---|---|
GET | /api/marketplace/artifacts | List marketplace artifacts. POST /publish submits one (publisher accounts only). |
POST | /api/marketplace/payments/initialize | Initialize a marketplace purchase. |
GET · POST | /api/oauth/clients | List / create partner OAuth client apps. |
GET | /api/oauth/connections | List the OAuth connections this World holds to third-party providers. |
Health endpoints
| Method | Path | Description |
|---|---|---|
GET | /health | Check API health. Returns { status, version, timestamp, uptime }. |
Receipt endpoints
A change is proposed as a Receipt and accepted one instruction at a time.
| Method | Path | Description |
|---|---|---|
POST | /api/phico/receipt/generate | Compose a Receipt for a surface. |
GET | /api/phico/receipt/:receiptId | Fetch a Receipt with its ordered instructions. |
POST | /api/phico/receipt/:receiptId/instruction/:instructionId/accept | Accept and apply one instruction. Instructions you do not accept are never applied. |
POST | /api/phico/receipt/:receiptId/save | Save the Receipt’s current state. |
POST | /api/phico/receipt/intent/distill | Turn a long brief into a short one before composing. |
Analytics endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/analytics/dashboard | The headline metrics for a period. |
GET | /api/analytics/events | Raw events, filtered and paginated. |
GET | /api/analytics/aggregates | Pre-aggregated series for a period. |
GET | /api/analytics/surfaces/:surfaceId | The same figures, narrowed to one surface. |
GET | /api/analytics/export | Export the period’s events as CSV. |
POST | /api/analytics/events · /events/batch | Record your own events. |
Machine-readable schema
Two machine-readable descriptions, and they answer different questions.
GET /api/docs/openapi.json is the OpenAPI 3.0.3 specification for this
API — every path, method, parameter and schema. GET /api/docs/openapi.yaml
serves the same document in YAML, and GET /api/docs renders it as browsable
Swagger UI. None of the three needs authentication.
GET /api/meta/schema returns the derived context schema — the machine
view AI tooling consumes: the blocks, capabilities and settings available in
the current World. That is not in the OpenAPI document, because it describes
your World rather than the API.