Skip to main content
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_modeWho can view the site
publicAnyone with the URL (the default for websites)
accountSigned-in members of your account
admins_onlyAccount admins only
me_onlyJust 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.

​
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 POST https://api.crevio.co/v1/domains/dom_abc123/assign \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "site": "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"
Keys prefixed with CREVIO_ are reserved for platform-injected values and can’t be set by hand. 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.

​
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.