Change the free web address

change_subdomain

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

POST /v1/change_subdomainScopesites:writeDestructive

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.

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.

This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an Idempotency-Key header whenever you might retry it.

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.

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 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 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 explains every status code a call can answer with.