---
title: add_domain, update_domain, purchase_domain
description: Connect and manage custom domains with automatic SSL and DNS management.
section: MCP Reference
order: 12
---

# add_domain, update_domain, purchase_domain

Connect custom domains to websites with automatic SSL and optional DNS management.

Domain details are included in `get_website` responses.

## Actions

### add

Add a custom domain.

**Parameters:**
- `website` — Website subdomain, domain, or UUID
- `domain` — Domain name (e.g., `example.com`)
- `dns_managed` — (optional) Enable DNS management

### update

Update a domain. Currently supports toggling DNS management.
Domain names cannot be changed after creation.

**Parameters:**
- `domain` — Domain name to update (e.g., `example.com`)
- `dns_managed` — Enable or disable DNS management

## DNS Setup

There are two ways to point a custom domain at PageWeave. In both cases, SSL is provisioned automatically via on-demand TLS once DNS resolves to our servers.

### Flow A — PageWeave manages DNS (recommended)

Let PageWeave run the domain's DNS. This is the default for domains purchased through PageWeave and is enabled by toggling DNS management on a connected domain.

1. Enable DNS management on the domain (`dns_managed: true`).
2. At your registrar, delegate the domain's nameservers to PageWeave:
   - `ns1.pageweave.dev`
   - `ns2.pageweave.dev`
   - `ns3.pageweave.dev`
   - `ns4.pageweave.dev`
3. PageWeave auto-provisions the required records — **ALIAS** at the zone root and **CNAME** for `www` — both pointing at `<subdomain>.pageweave.site`.

No manual record entry is needed. DNS record management for delegated zones is available via the REST API (`dns:read` / `dns:manage` OAuth scopes), not via MCP tools.

### Flow B — You keep your DNS

Keep your existing DNS provider and add records pointing at `<subdomain>.pageweave.site`:

| Host | Type | Value |
|------|------|-------|
| Apex / root (`example.com`) | **ALIAS** / ANAME (or an A record) | `<subdomain>.pageweave.site` |
| Subdomain (`www.example.com`) | **CNAME** | `<subdomain>.pageweave.site` |

> **Do not use CNAME at the zone apex.** A CNAME cannot coexist with the SOA and NS records required at the root, per [RFC 1034 §3.6.2](https://www.ietf.org/rfc/rfc1034.html) (clarified by [RFC 2181](https://www.rfc-editor.org/rfc/rfc2181)). BIND and other authoritative servers refuse to load such a zone. Use one of the apex-safe equivalents instead:
> - **ALIAS** — ClouDNS, Google Cloud DNS, PowerDNS
> - **ANAME** — name used by many registrars and DNS providers
> - **Alias record** — AWS Route 53
> - **CNAME flattening** — Cloudflare
>
> These are provider-side features (no IETF standard yet) that resolve the target hostname server-side and return synthesized A/AAAA records. CNAME remains the correct choice for any subdomain (`www`, `blog`, etc.).

## OAuth Scopes

| Action | Scope |
|--------|-------|
| add | `website:create` |
| update | `website:edit` |