Sites (AI website builder)

A Site is an AI-built, fully-hosted website that Crevio creates from a one-paragraph brief — you describe the brand and what you sell, and an engineering agent writes the code, deploys it, and gives you back a live URL. You don’t pick a template or wire up hosting. You POST /sites with a prompt, Crevio kicks off an AI build, and you poll a Task until the site is live at a *.crevio.app subdomain. From there the API exposes the whole platform surface around the site: visitor analytics, the site’s own database, encrypted secrets (env vars), custom domains, and deployment history. Sites use the site_ prefix and have the object type site.

Build a site from a prompt

The prompt is a build brief — describe the brand, what you sell, and the look and feel. Crevio’s engineering agent turns it into a real codebase and deploys it. The response comes back immediately with a build_task_id you poll to watch the build.

curl -X POST https://api.crevio.co/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A clean, modern landing site for a ceramics studio called Kiln & Co. Earthy palette, hero with a newsletter signup, a shop section, and an about page. Warm and handmade feel.",
    "name": "Kiln & Co",
    "access_mode": "public"
  }'

import { Crevio } from "@crevio/sdk";

const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });

const site = await crevio.sites.create({
  prompt:
    "A clean, modern landing site for a ceramics studio called Kiln & Co. " +
    "Earthy palette, hero with a newsletter signup, a shop section, and an about page.",
  name: "Kiln & Co",
  access_mode: "public",
});

Build me a website for my ceramics studio "Kiln & Co" — earthy,
handmade feel, with a shop and a newsletter signup.

The response includes the build task to poll plus the addressable URLs:

{
  "id": "site_abc123",
  "object": "site",
  "name": "Kiln & Co",
  "subdomain": "kiln-and-co",
  "app_url": "https://kiln-and-co.crevio.app",
  "is_live": false,
  "access_mode": "public",
  "show_referral_badge": true,
  "build_task_id": "task_def456",
  "domain": null,
  "domain_verified": false,
  "github_repo_full_name": "crevio-sites/kiln-and-co"
}

The site is created instantly, but is_live is false until the AI build finishes. The build runs as a Task — that’s what build_task_id is for.

Poll the build task

A build is an engineering agent Task. Poll it until its status settles, then check the site’s is_live.

# Watch the build task
curl https://api.crevio.co/v1/tasks/task_def456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Then confirm the site is live
curl https://api.crevio.co/v1/sites/site_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const task = await crevio.tasks.get({ id: "task_def456" });

if (task.status === "completed") {
  const site = await crevio.sites.get({ id: "site_abc123" });
  console.log(site.is_live, site.app_url);
}

Prefer not to poll? Subscribe to the task_run.completed webhook and react when the build finishes. See Webhooks.

Start from an existing GitHub repo

Already have a codebase? Pass repository (an owner/repo you’ve connected) instead of a prompt. Crevio mounts that repo as the site’s workspace, so the engineering agent — and your build/deploy pipeline — work directly against your code.

curl -X POST https://api.crevio.co/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "kiln-co/website",
    "name": "Kiln & Co Website",
    "access_mode": "account"
  }'

prompt is required unless you provide repository. One or the other must be present.

Access modes and visibility

access_mode controls who can reach the deployed site. Gating is enforced at the edge, not just in the app.

`access_mode`	Who can view the site
`public`	Anyone with the URL (the default for websites)
`members`	Your customers — anyone with a customer record on your account — plus your team
`account`	Signed-in members of your account’s team
`admins_only`	Account admins only
`me_only`	Just you — useful while a build is in progress

The show_referral_badge flag toggles the “Powered by Crevio” badge. It defaults to on for all plans, and turning it off requires the Business plan — on any other plan, PATCH /sites/{id} with show_referral_badge: false returns 402 with code plan_required and param: "show_referral_badge", and nothing in the request is applied. Turning it back on is always allowed.

Member sessions

When a viewer signs in to a deployed site, the edge sets a host-only session cookie on that site’s own hostname and forwards a signed token to your app on every request as x-crevio-user-token. Verify it with verifyUserToken() from @crevio/sdk; it returns the viewer’s id and kind:

`kind`	`userId`	Who
`member`	`cus_…`	One of your customers. Use this id with `access.check` and `customers.get`.
`platform`	`user_…`	A member of your Crevio team.

A site’s signed-in viewer is identified as your customer, not as a Crevio account — so the same person who bought from your store is the same cus_… id you see in orders, grants and the customer list. A development preview (<site>--preview-<id>.crevio.app) opens only to your Crevio team, and forwards the same header for the team member viewing it: kind is platform and userId is their user_… id. The token is bound to the preview host, so verify it without audience: passing the deployed site’s worker name rejects it. Sign-out is a hosted URL on the site’s own host, so a members area can link to it without owning any session code:

https://<your-site-host>/__crevio/auth/logout?return_to=/

It clears the site’s session cookie and redirects to return_to (a same-origin path; anything else falls back to /). It ends the session on that site only — it never signs the viewer out of Crevio itself. Sessions cannot be ended from inside your app’s code: the cookie is HttpOnly and set by the edge, which is what makes it impossible for a page to leak or forge one. Link to the URL above instead. Billing is a hosted URL too. It opens your store’s billing page on billing.crevio.co for the signed-in customer:

https://<your-site-host>/__crevio/billing?return_to=/dashboard

The customer can update their payment method and billing address, download invoices, and cancel or renew subscriptions (payment plans run to their final payment). The page’s Return link goes back to return_to (a same-origin path). A signed-out visitor is sent to sign in first. Link to it with a full navigation (a plain <a href>), not a fetch.

Custom domains

A new site lives at https://<subdomain>.crevio.app. To put it on your own domain, attach one — either bought through Crevio or one you already own — then verify it. The full purchase-and-attach flow lives in Domains; the short version:

# Attach a domain you own (or bought via Crevio) to this site
curl -X PATCH https://api.crevio.co/v1/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "site_id": "site_abc123" }'

# Then verify DNS
curl -X POST https://api.crevio.co/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Once verified, the site’s domain and domain_verified fields update.

The platform surface around a site

Beyond the website itself, each site exposes the operational tooling Crevio runs on its behalf.

Site analytics

Pull visitor and traffic analytics for a site.

curl https://api.crevio.co/v1/sites/site_abc123/analytics \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Site database

Sites get a real database. Inspect the schema and run read queries through the API — handy for letting an agent answer “how many signups this week?” without leaving Crevio.

# List the tables
curl https://api.crevio.co/v1/sites/site_abc123/db/tables \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Run a query
curl -X POST https://api.crevio.co/v1/sites/site_abc123/db/query \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT count(*) FROM newsletter_signups WHERE created_at > now() - interval '\''7 days'\''" }'

Site secrets (encrypted env vars)

Sites need API keys and config — Stripe keys, a third-party token, a feature flag. Store them as encrypted secrets that are injected into the deployed worker as environment variables. Values are write-once-readable: list shows masked values, and you reveal a single secret explicitly. A secret takes a name (required), a value (required), and an optional description. The name must be uppercase letters, digits, and underscores, and cannot start with a digit.

curl https://api.crevio.co/v1/sites/site_abc123/secrets \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -X POST https://api.crevio.co/v1/sites/site_abc123/secrets \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "STRIPE_SECRET_KEY",
    "value": "sk_live_...",
    "description": "Live Stripe secret key"
  }'

curl https://api.crevio.co/v1/sites/site_abc123/secrets/STRIPE_SECRET_KEY/reveal \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -X DELETE https://api.crevio.co/v1/sites/site_abc123/secrets/STRIPE_SECRET_KEY \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The names Crevio sets on every site (CREVIO_API_KEY, CREVIO_APP_URL, CREVIO_API_BASE_URL, CREVIO_AI_GATEWAY_URL, CREVIO_ACCOUNT_ID, CREVIO_SITE_AUDIENCE, CREVIO_JWKS_URL, CREVIO_SIGN_IN_URL) can’t be set by hand; any other name, including other CREVIO_ ones, is yours. Removing a secret also removes it from the live worker.

Deployments

Every build and redeploy is recorded. List deployment history to see what’s live, building, or failed.

curl https://api.crevio.co/v1/sites/site_abc123/deployments \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Deploys run asynchronously. Triggering a deploy returns immediately and the build continues in the background — a single deploy can take several minutes. Poll the deployments list (or watch for the deploy to finish) rather than expecting a synchronous result. You’ll see statuses like building, live, and failed with the live URL once it’s up.

Template upgrades

A Crevio-hosted site keeps the storefront template it was forked from. GET /sites/{id}/template returns its generation and template_commit, the latest_generation and latest_commit, a pinned archive_url for that commit, and upgrade_available, which is true when the site is on an older generation or commit (or its commit can’t be told). A site built from your own GitHub repo never runs the template, and the endpoint answers 422 repository_not_hosted. The port itself is ordinary repository work: back up, port onto the new template, test on the preview, then deploy. As the last step, POST /sites/{id}/template/confirm records that the site now runs the current generation. It changes no code and deploys nothing. For a live site it is refused with 422 upgrade_not_live while production runs different code from main, and with 422 repository_not_hosted for a site on your own repo. Confirming needs the permission to publish sites. Asking the agent to “update my site to the latest version” runs this whole flow for you, and restores the site if anything fails.

Next steps

Domains

Buy a domain and attach it to your site.

Tasks

Understand the Task you poll while a site builds.

Webhooks

Get notified when a build completes instead of polling.

Usage & credits

See how AI builds and deploys draw down credits.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Sites (AI website builder)

Build a site from a prompt

Poll the build task

Start from an existing GitHub repo

Access modes and visibility

Member sessions

Custom domains

The platform surface around a site

Site analytics

Site database

Site secrets (encrypted env vars)

Deployments

Template upgrades

Next steps

Domains

Tasks

Webhooks

Usage & credits

​Build a site from a prompt

​Poll the build task

​Start from an existing GitHub repo

​Access modes and visibility

​Member sessions

​Custom domains

​The platform surface around a site

​Site analytics

​Site database

​Site secrets (encrypted env vars)

​Deployments

​Template upgrades

​Next steps

Domains

Tasks

Webhooks

Usage & credits

Build a site from a prompt

Poll the build task

Start from an existing GitHub repo

Access modes and visibility

Member sessions

Custom domains

The platform surface around a site

Site analytics

Site database

Site secrets (encrypted env vars)

Deployments

Template upgrades

Next steps