AI integration
Everything PhiCo does in the product is also reachable over REST. This page is for the case where something outside PhiWebs has to generate or revise a page.
The composer endpoint
POST /api/ai/composer/stream is the composer — the same pipeline the
product uses. It streams its answer over SSE; there is no non-streaming
variant.
const res = await fetch(`${baseUrl}/api/ai/composer/stream`, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${token}`,
},
body: JSON.stringify({
intent: 'A landing page for a SaaS product with pricing',
context: { worldId: 'wld_123' },
}),
})For short, non-streaming prompts use POST /api/ai/complete.
Long model calls are handled as jobs rather than held open on the request: an endpoint may hand you a job to poll instead of blocking until the model finishes.
Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
POST | /api/ai/composer/stream | Stream a composer turn (SSE). |
POST | /api/ai/complete | Synchronous completion for short prompts. |
POST | /api/ai/analyze | Analyse a surface or block tree. |
POST | /api/ai/embed | Generate embeddings. |
GET | /api/ai/models | The models available to this World. |
GET | /api/ai/metrics | Per-agent usage for the current day. |
GET | /api/ai/usage | Φ spend per period. |
GET | /api/ai/credits/balance | Remaining Φ. |
GET · POST | /api/ai/agents | List / create custom agents. |
GET · PUT · DELETE | /api/ai/agents/:id | Read / update / delete one. |
What it costs
Every call that runs a model spends Φ, metered by the work it produces. How much Φ arrives each month, and how fast it may be spent, are set by the World’s plan; the Wallet page of the account shows the figures. See Rate limits & quotas and Billing & plans.
Best practices
- Be specific. Say the audience, the sections you need and the tone. Vague briefs produce generic pages.
- Iterate. Start with a rough generation and refine it in follow-up turns; the thread keeps its context.
- Review before publishing. A proposal is a proposal — read the Receipt.
- Point at examples. An existing surface is the fastest way to describe a style.
See also
- PhiCo — the composer, in the product
- Receipts — what a composer turn produces
- API reference — everything else