API & agents

Build sites programmatically — from your own scripts, tools, or an AI agent like a personal “Jarvis” — using a personal API key and the public build endpoint.

1. Get an API key

Go to Settings → API keys, create a key, and copy it (it’s shown once). Keys look like wf_live_…. Keep it secret — treat it like a password. You can revoke a key any time.

2. Build a site

Send a POST to /api/v1/generate with your key as a Bearer token:

curl -X POST https://webforgia.com/api/v1/generate \
  -H "Authorization: Bearer wf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a booking site for a barber shop",
    "buildType": "website"
  }'

The response includes the generated spec and a link to open it in the builder:

{
  "projectId": "…",
  "editorUrl": "https://webforgia.com/builder?project=…",
  "spec": { … },
  "model": "…",
  "credits": { "freeRemaining": 0, "purchased": 12 }
}

Request fields

prompt (required) — what to build, in plain language.
buildType — website (default), design, slides, document, or dataviz.
mode — lite, economy, or power (reasoning effort).
save — true by default (creates a project you can open); set false to only return the spec.

Use it from an agent (MCP)

For agents, run the bundled Webforgia MCP server (see /mcp in the repo). It exposes a build_website tool so any MCP-capable agent can build a site as a native tool call — point it at your API key via the WEBFORGIA_API_KEY environment variable.

Limits & billing

Each successful build uses one build credit (same pool as the dashboard).
Rate limit: 20 builds per 5 minutes.
401 = bad/missing key · 402 = out of credits · 400 = bad request · 503 = a required model key isn’t configured.

The tenant is derived from the key — a key can only ever build in its own workspace. Keys are stored hashed; only the last-used time and a short prefix are ever shown back to you.