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

# Domains

> Search, buy, and attach custom domains to your AI-built sites — or connect a domain you already own — and manage DNS zone records, all through the API.

**Domains let you put a Crevio Site on your own custom address — search for an available name, buy it, attach it to a site, and verify it, or connect a domain you already own.**

A freshly built [Site](/developer/guides/sites) lives at `https://<subdomain>.crevio.app`. The Domains API is how you move it to `https://yourbrand.com`. You can just ask Crevio to find and buy a name, or drive the full flow yourself: **search → purchase → assign → verify**. Connecting an existing domain skips the purchase step.

Domains carry their own resource ID, returned by the purchase and connect calls.

## The flow at a glance

<Steps>
  <Step title="Search for a buyable domain">
    `GET /domains/search` returns available names and prices.
  </Step>

  <Step title="Purchase it">
    `POST /domains/purchase` registers the domain to your account.
  </Step>

  <Step title="Assign it to a site">
    `POST /domains/{id}/assign` points the domain at one of your sites.
  </Step>

  <Step title="Verify DNS">
    `POST /domains/{id}/verify` confirms DNS is configured and goes live.
  </Step>
</Steps>

## Worked example: buy a domain and attach it to a site

### 1. Search for an available domain

```bash theme={null}
curl "https://api.crevio.co/v1/domains/search?query=kilnandco" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

The result lists available names with prices so you can pick one to buy.

### 2. Purchase it

`domain` is required.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crevio.co/v1/domains/purchase \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "domain": "kilnandco.com" }'
  ```

  ```typescript SDK theme={null}
  import { Crevio } from "@crevio/sdk";

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

  const domain = await crevio.domains.purchase({ domain: "kilnandco.com" });
  ```

  ```text MCP (agent) theme={null}
  Buy kilnandco.com and put my Kiln & Co site on it.
  ```
</CodeGroup>

This returns the domain's resource ID, which you'll use in the next steps.

### 3. Assign it to a site

Point the domain at the site you want it to serve. Pass the target site as `site` (required).

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

### 4. Verify

Verification confirms DNS is pointed correctly and brings the domain live. For domains bought through Crevio, DNS is managed for you; for connected domains, verification checks the records you added (see below).

```bash theme={null}
curl -X POST https://api.crevio.co/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

<Note>
  Verification can take time to propagate. If it doesn't pass immediately, the platform re-checks in the background, so a verify that returns "pending" will often resolve on its own.
</Note>

## Connect a domain you already own

If you registered a domain elsewhere, connect it instead of purchasing. Crevio gives you the DNS records to add at your registrar, then you verify.

| Field         | Purpose                                                              |
| ------------- | -------------------------------------------------------------------- |
| `domain`      | The domain (or subdomain) to connect — required                      |
| `site`        | The site to attach it to — optional, defaults to your account's site |
| `setup_email` | `true` to also configure email DNS for the domain                    |

```bash theme={null}
curl -X POST https://api.crevio.co/v1/domains/connect \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com",
    "site": "site_abc123",
    "setup_email": true
  }'
```

If you don't pass `site` here, assign it to a site afterward; then verify exactly as above.

## DNS zone management

For domains Crevio manages, you can read and edit DNS records directly — add an MX record for email, a TXT record for verification, or a CNAME for a subdomain.

<CodeGroup>
  ```bash List records theme={null}
  # All resolved DNS records for the domain
  curl https://api.crevio.co/v1/domains/dom_abc123/dns-records \
    -H "Authorization: Bearer YOUR_API_TOKEN"

  # Editable zone records
  curl https://api.crevio.co/v1/domains/dom_abc123/zone-records \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```bash Add a record theme={null}
  curl -X POST https://api.crevio.co/v1/domains/dom_abc123/zone-records \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "TXT",
      "name": "@",
      "content": "v=spf1 include:_spf.crevio.co ~all"
    }'
  ```

  ```bash Delete a record theme={null}
  curl -X DELETE https://api.crevio.co/v1/domains/dom_abc123/zone-records/rec_xyz789 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</CodeGroup>

<Tip>
  Use `GET /domains/{id}/dns-records` to see everything currently resolving (including platform-managed records), and `GET /domains/{id}/zone-records` for the records you can edit.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Sites" icon="window" href="/developer/guides/sites">
    Build the site you'll attach this domain to.
  </Card>

  <Card title="Email" icon="envelope" href="/developer/guides/email">
    Verify a sending domain so email comes from your address.
  </Card>

  <Card title="API reference" icon="book" href="/developer/api-reference/introduction">
    Every domain endpoint and parameter.
  </Card>

  <Card title="Usage & credits" icon="coins" href="/developer/guides/usage-billing">
    How domain registration is billed.
  </Card>
</CardGroup>