> ## 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 — with email as a capability on the same domain, all through the API.

**A domain is one resource with capabilities: it can serve your storefront (`web`), send email (`email_sending`), and receive email (`email_receiving`) — search for a name, buy it or connect one you own, and verify.**

A freshly built [Site](/docs/developer/guides/sites) lives at `https://<subdomain>.crevio.app`. The Domains API moves it to `https://yourbrand.com`. Buy through Crevio and DNS is configured for you automatically — zero records to add. Connect a domain you own and the response tells you exactly which records to add and tracks each one individually.

Domains carry their own resource ID, returned by the purchase and create 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 — or connect your own">
    `POST /domains/purchase` registers the domain and auto-configures every DNS record. `POST /domains` connects a domain you already own.
  </Step>

  <Step title="Check what's left">
    `GET /domains/{id}` returns per-capability statuses, every DNS record with its own status, and a `next_step` sentence.
  </Step>

  <Step title="Verify">
    `POST /domains/{id}/verify` confirms DNS 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>

Crevio owns the DNS zone for purchased domains, so routing and email records are written for you — poll `GET /domains/{id}` until the capabilities you care about read `active`.

`GET /domains/{id}` carries `purchase_status` for domains bought through Crevio, and `next_step` spells the same thing out in a sentence. It's the answer to "did my payment go through?" — the DNS capabilities stay `pending` until the registration lands, so read the purchase first:

| `purchase_status` | What it means                                                                   |
| ----------------- | ------------------------------------------------------------------------------- |
| `pending_payment` | Nothing charged, nothing registered. Finish the checkout.                       |
| `registering`     | Paid. The registrar is registering it — usually a few minutes. Don't pay again. |
| `registered`      | Bought and yours. DNS setup continues under `capabilities`.                     |
| `failed`          | Registration failed and the payment was released — nothing was charged.         |

Domain purchases are platform charges, not storefront orders, so they never appear in `GET /orders`.

<Note>
  With no card on file the response carries a `checkout_url` instead, and the domain sits at `pending_payment` until it's paid. Checkout links expire after a day — call `POST /domains/purchase` again for the same domain to get a fresh one. A domain that's already paid for (`registering`) or already yours (`registered`) refuses a repeat purchase and says so.
</Note>

### 3. Assign it to a site

Site assignment is an attribute — set `site_id` (or pass it at create time). `"site_id": null` detaches.

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

### 4. Verify

Verification is idempotent and re-checks every enabled capability. Scope it with `?capability=web|email_sending|email_receiving` to skip the other providers' checks.

```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, create it instead of purchasing. The response carries the DNS records to add at your registrar — each with its own `status` — plus a `next_step` telling you whose move it is.

| Field          | Purpose                                                                       |
| -------------- | ----------------------------------------------------------------------------- |
| `name`         | The domain (or subdomain) to connect — required                               |
| `site_id`      | The site to attach it to — optional, defaults to your account's site          |
| `capabilities` | e.g. `{ "email_sending": true }` to also set up sending email from the domain |

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

`GET /domains/{id}` is the source of truth while you set up DNS: `records[]` shows each record as `pending` or `verified`, and `capabilities` shows `web` / `email_sending` / `email_receiving` as `pending`, `active`, `error`, or `null` (off). Toggle capabilities later with `PATCH /domains/{id} { "capabilities": { ... } }`.

## DNS zone management

For domains purchased through Crevio, the DNS zone itself is manageable — add an MX record, a TXT verification record, or a CNAME for a subdomain. The zone's ID is on the domain payload as `zone_id`.

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

  ```bash Add a record theme={null}
  curl -X PUT https://api.crevio.co/v1/zones/zone_abc123/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/zones/zone_abc123/records/rec_xyz789 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</CodeGroup>

<Tip>
  Connected (bring-your-own) domains have no zone — their DNS lives at your registrar. `GET /domains/{id}` still shows you every record Crevio expects and whether it resolves.
</Tip>

## Next steps

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

  <Card title="Email" icon="envelope" href="/docs/developer/guides/email">
    Send from your own address once email\_sending is active.
  </Card>

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

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