Developers
API
Build projects from your own code, scripts or agents with an API key and one endpoint.
Build a project
Send a POST to /api/v1/generate with an API key that has the write scope:
Request
curl -X POST https://webforgia.com/api/v1/generate \
-H "Authorization: Bearer $WEBFORGIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A booking site for a barber shop in Leeds",
"buildType": "website",
"mode": "economy"
}'Request fields
| Field | Type | |
|---|---|---|
prompt | string, required | What to build, 3 to 16,000 characters. |
buildType | string | website (default), design, slides, document or dataviz. |
mode | string | lite, economy or power. See Build Generation. |
save | boolean | Save the result as a project you can open in the builder. Default true; false returns the specification only. |
Response
200 OK
{
"projectId": "…",
"editorUrl": "https://webforgia.com/builder?project=…",
"spec": { … },
"usage": { … },
"credits": { … }
}projectIdandeditorUrlare null whensaveis false.specis the full Site Specification.usageandcreditsdescribe what the build used and what the workspace has left.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | — | The body is not valid — check the fields above. |
| 401 | — | No API key, or an invalid, expired or revoked one. |
| 402 | out_of_credits | The workspace has no credit for a build. |
| 403 | insufficient_scope | The key does not have the write scope. |
| 429 | rate_limited | Too many requests — 20 builds per 5 minutes from one address. Retry after a pause. |
| 5xx | timeout, provider_busy, failed | The build could not finish. Not charged; the body says whether it is retryable. |
Error bodies are { "error": "…", "code": "…", "retryable": true }.
Beyond building
Listing projects, reading a specification and publishing are available through the MCP API, which works from any HTTP client as well as from AI assistants.