> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sites (AI website builder)

> Describe what you want and Crevio's AI builds, deploys, and runs a real website for you — then manage its analytics, database, secrets, domains, and deployments through the API.

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript SDK theme={null}
  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",
  });
  ```

  ```text MCP (agent) theme={null}
  Build me a website for my ceramics studio "Kiln & Co" — earthy,
  handmade feel, with a shop and a newsletter signup.
  ```
</CodeGroup>

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

```json theme={null}
{
  "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"
}
```

<Note>
  The site is created instantly, but `is_live` is `false` until the AI build finishes. The build runs as a [Task](/developer/guides/tasks) — that's what `build_task_id` is for.
</Note>

### Poll the build task

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

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```typescript SDK theme={null}
  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);
  }
  ```
</CodeGroup>

<Tip>
  Prefer not to poll? Subscribe to the `task_run.completed` webhook and react when the build finishes. See [Webhooks](/developer/guides/webhooks).
</Tip>

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

```bash theme={null}
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"
  }'
```

<Note>
  `prompt` is required **unless** you provide `repository`. One or the other must be present.
</Note>

## 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) |
| `account`     | Signed-in members of your account              |
| `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.

## 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](/developer/guides/domains); the short version:

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
# 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.

<CodeGroup>
  ```bash List theme={null}
  curl https://api.crevio.co/v1/sites/site_abc123/secrets \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```bash Add theme={null}
  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"
    }'
  ```

  ```bash Reveal theme={null}
  curl https://api.crevio.co/v1/sites/site_abc123/secrets/STRIPE_SECRET_KEY/reveal \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```bash Remove theme={null}
  curl -X DELETE https://api.crevio.co/v1/sites/site_abc123/secrets/STRIPE_SECRET_KEY \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

### Deployments

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

```bash theme={null}
curl https://api.crevio.co/v1/sites/site_abc123/deployments \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

<Warning>
  **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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Domains" icon="globe" href="/developer/guides/domains">
    Buy a domain and attach it to your site.
  </Card>

  <Card title="Tasks" icon="robot" href="/developer/guides/tasks">
    Understand the Task you poll while a site builds.
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer/guides/webhooks">
    Get notified when a build completes instead of polling.
  </Card>

  <Card title="Usage & credits" icon="coins" href="/developer/guides/usage-billing">
    See how AI builds and deploys draw down credits.
  </Card>
</CardGroup>