add_custom_domain

A site can have up to 10 custom domains, and each one serves the same site alongside the others. Adding one requires a paid plan and the Manage domains permission, and is refused on a free workspace.

Pass a bare hostname. A value with http:// or https://, a path, or fewer than 4 or more than 253 characters is refused with the same messages as the Custom Domain field, and so is a Modulify address. A hostname belongs to one site only, so a domain this site or another site already has is refused, and so is any domain once the site has 10.

For a root domain the www companion is added too, unless that www hostname is already taken, and passing www.example.com adds example.com with www.example.com as its companion. When the domain it adds, or the companion added with it, is the domain waiting on verification, that pending verification is cleared.

The answer carries the new domainId and the full domains list. Adding does not make the domain live: read the records to add with get_domain_status, then call it again once they are in place, because that call re-checks DNS and flips the domain to connected. verify_domain plays no part here, since it belongs to the separate start_domain_verification flow and is refused when nothing is pending.

The site keeps serving its free address and its other domains throughout. See Connect a custom domain.

Request

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

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

curl -X POST https://api.modulify.ai/v1/add_custom_domain \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","domain":"DOMAIN"}'

Over MCP, the same method is the add_custom_domain tool.

Inputs

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.