fromscratch
Help center

Generate sites with the API

Create an API key, start a site generation with POST /v1/sites, poll until it's ready, then get the public URL and a screenshot — from your own app.

Updated 3 min read
On this page
  1. Before you start
  2. 1. Create an API key
  3. 2. Authenticate
  4. 3. Start a generation
  5. 4. Poll until it's ready
  6. 5. Update, cancel or delete
  7. Errors
  8. Try it in the browser
  9. Related

The developer API lets your own application create FromScratch sites without opening the chat: you send a description (and optional reference files), FromScratch builds the site, publishes it and returns its public URL and a screenshot. It's how agencies, directories and automation tools generate sites in bulk.

Before you start

  • The developer API is included in the Starter and Pro plans. On the Free plan the Developer page shows « Developer mode is reserved for paid plans ».
  • Generations use your credits, exactly like building in the chat (How credits work).
  • Sites created by the API are normal projects: you find them on your Home page, can open them, chat with the agent and republish.

1. Create an API key

  1. Open the user menu and click Developer. The Developer mode page opens.
  2. In API keys, type a name (« Key name (Production, Zapier…) ») and click + Generate.
  3. Copy the key right away: « New key — copy it now, it won't be shown again ». Keys start with fs_live_. FromScratch only stores a fingerprint of the key, so it can't show it to you later.
  4. Each key shows when it was last used. Revoke cuts it off immediately: apps using it stop working.

Warning

Treat a key like a password. Keep it on your server (an environment variable), never in a web page, a mobile app or a public repository. If a key leaks, revoke it and generate a new one.

2. Authenticate

Every request sends the key in the Authorization header. The base URL is https://from-scratch.app.

curl https://from-scratch.app/v1/models \
  -H "Authorization: Bearer $FS_API_KEY"

GET /v1/models lists the model ids you can pass as model (one is marked is_default).

3. Start a generation

POST /v1/sites takes multipart/form-data:

Field Required What it is
prompt yes The description of the site to build.
name no Project name (otherwise derived from the prompt).
template no Starting template (default: auto).
folder no A folder path such as paris/barbers, created if missing — the project lands there on your Home page.
model no A model id from GET /v1/models.
files no Reference files (images, PDF, data…), up to 20, max 15 MB each. They're added to the project and given to the agent. 
curl -X POST https://from-scratch.app/v1/sites \
  -H "Authorization: Bearer $FS_API_KEY" \
  -F prompt="A one-page site for Fade Factory, a barbershop in Lyon: services with prices, opening hours, a booking request form" \
  -F folder="lyon/barbers" \
  -F files=@logo.png \
  -F files=@price-list.pdf

The answer comes at once, with status 202 and a job id:

{"id": "6f1c…", "status": "queued", "url": null, "screenshot_url": null}

4. Poll until it's ready

GET /v1/sites/{id} returns the job. Its status moves through queued → building → publishing → capturing → ready, or ends in error or cancelled. Poll every 10 to 15 seconds; a generation takes minutes, not seconds.

curl https://from-scratch.app/v1/sites/6f1c… \
  -H "Authorization: Bearer $FS_API_KEY"

At ready the job carries:

  • url — the public address of the published site;
  • screenshot_url — a PNG capture (best effort: it can be null if the capture wasn't possible);
  • project_id, folder, error (on failure) and cost (tokens used, credits charged).

GET /v1/sites/{id}/screenshot returns the PNG itself.

Note

API generations build in one go: there's no step-by-step plan to approve, and the site is published automatically at the end.

5. Update, cancel or delete

  • POST /v1/sites/{id}/amend — prompt (+ optional files): the agent changes the existing site, then it's republished. Poll the same id again.
  • POST /v1/sites/{id}/cancel — stops a generation that is queued or building.
  • DELETE /v1/sites/{id} — permanently deletes the published site, its workspace and all its data.
  • GET /v1/published?folder=paris — all your published sites (made by the API or in the app), optionally under a folder path.

Errors

Code Meaning
400 Empty prompt, or unknown model.
401 Missing, invalid or revoked key.
403 Account unavailable, or your plan doesn't include the developer API.
404 No such job for your account.
409 A generation is already running (amend), or nothing to cancel.
413 A file is larger than 15 MB.

Try it in the browser

The Developer page includes the API explorer — try every endpoint: paste your key at the top, fill the parameters, click ▶ Send, and use Poll until ready to follow a job live. Recent generations lists your latest jobs with a View ↗ link.

Was this page helpful?