# add_www_domain

Source: https://modulify.ai/docs/api/domains/add-www-domain

Adds the www version of one of a site's custom domains, so the root and the www address both reach the site.

- Title: Add the www companion domain
- Scope: `config:write`
- Access: Makes changes
- Endpoint: `POST /v1/add_www_domain`

Usually you do not need it, because `add_custom_domain` and `verify_domain` already attach the www companion for a root domain. Reach for it after `remove_www_domain`, or when `get_domain_status` shows no companion on a root domain because the automatic attempt did not complete.

It requires a paid plan and the **Manage domains** permission. The companion only exists for root domains, so a domain that is itself a subdomain is refused, and so is one that already has a companion or whose www hostname already belongs to this site or another one.

When the domain is itself the www hostname, because its root was removed, it adds the root back instead. When the hostname it adds is the domain waiting on verification, that pending verification is cleared.

Like the domain itself, the companion is not live until its DNS records are in place, so call `get_domain_status` afterwards to read what to add. See [www and apex domains](https://modulify.ai/docs/publish/www-and-apex).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/add_www_domain`, sending the inputs below as a JSON object. The token needs the `config:write` scope.

It makes changes, so send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
curl -X POST https://api.modulify.ai/v1/add_www_domain \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","domainId":"DOMAIN_ID"}'
```

Over MCP, the same method is the [add_www_domain tool](https://modulify.ai/docs/mcp/domains/add-www-domain).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |
| `domainId` | string | Yes | The `_id` of the custom domain to add the www companion to, as `get_domain_status` or `add_custom_domain` returned it. The companion is derived from that domain. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.