# change_subdomain

Source: https://modulify.ai/docs/api/sites/change-subdomain

Changes the free modulify.website address a site is served on, and the old address stops working at once.

- Title: Change the free web address
- Scope: `sites:write`
- Access: Destructive
- Endpoint: `POST /v1/change_subdomain`

This is the live public web address, so the old one stops resolving the moment this succeeds, and every link, bookmark or QR code pointing at it breaks. The tool tells the client to do this only when you have asked for this exact address. Custom domains, if the site has any, are not affected.

The CDN address of the site moves with the subdomain too. A published site, with custom domains or not, must be published again for its storage files, email sending and analytics API calls to keep working. Files linked by their full CDN address in pages or stored content, such as a public file embedded in a page, must be updated to the new address, because a publish alone does not change them.

The value is 3 to 63 characters of lowercase letters, numbers and single hyphens, never at either end, and it is lowercased for you. Reserved words and anything starting with `prj-` are refused. If another site anywhere on the platform already holds it, the call fails with `That subdomain is already taken!`, and `check_subdomain_available` tests a subdomain before you try. A locked site refuses the change. See [Your free web address](https://modulify.ai/docs/publish/your-web-address#changing-the-subdomain).

## Request

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

> **Warning**
>
> This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it.

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

Over MCP, the same method is the [change_subdomain tool](https://modulify.ai/docs/mcp/sites/change-subdomain).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |
| `subdomain` | string | Yes | The new address, without the `.modulify.website` suffix, for example `acme-bakery`. |

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