Connect a custom domain
Link a newsroom hostname, use its returned DNS instructions, and verify public availability before changing shared URLs.
A custom domain changes the address readers use for the Prezly-hosted newsroom. It does not deploy a custom Next.js website or configure its hosting provider. If you serve Prezly content through your own application, manage that application's domain with its own deployment setup.
Choose a subdomain you control, such as press.example.com. The hosted setup supports subdomains rather than a URL path like example.com/press; see the domain setup instructions. Keep hostname changes separate from story publication and newsroom availability.
Check access and current routing
Personal tokens use sites:read for domain list/detail, verification, and shareable instructions, and sites:write for linking/unlinking. The owner needs newsroom and custom-domain management permissions for linking and verification; linking also requires custom-domain feature access. A sufficient token scope alone does not grant those permissions. Load PREZLY_API_TOKEN using Your first API request.
curl --fail-with-body --silent --show-error 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/domains' \
--header "Authorization: Bearer $PREZLY_API_TOKEN" \
--header 'Accept: application/json'The response uses domains, without pagination. Each entry has domain_name, type, status, and instructions. Types distinguish the Prezly hostname, a custom domain, and reverse proxy routing. The Prezly hostname may have status: "redirect" when the custom domain is active. Reverse proxy setups are a different routing arrangement; these custom-domain operations do not replace their configuration.
Record the current hostname and where it is linked before changing it. Existing story links, campaigns, subscriptions, external integrations, and your own caches may contain the old URL.
Link the intended hostname
Replace press.example.com with your controlled subdomain before sending this illustrative request:
curl --fail-with-body --silent --show-error --request POST 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/domains' \
--header "Authorization: Bearer $PREZLY_API_TOKEN" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"domain":"press.example.com"}'The response is 200 OK with domain. A linked hostname can be inactive while its DNS is not ready. If DNS already matches, linking can activate it immediately. Linking a different hostname changes the newsroom's custom-domain setting; review the effect on existing addresses before doing so. A hostname already linked to another non-deleted, non-reverse-proxy newsroom is rejected.
Use the returned instructions[]: each instruction includes domain_name, DNS type, recommended_value, and is_valid. The CNAME target is specific to the newsroom/account configuration. Do not hard-code customers.prezly.com, copy another newsroom's target, or replace the target with the API base URL.
Configure DNS, then verify the result
Add the returned DNS record with the domain's authoritative DNS provider. This API does not itself edit records at that provider. Follow the provider setup guidance, including DNS-only configuration where a provider's proxy would interfere. DNS changes and HTTPS provisioning can take time; an accepted link request is not proof that the public site is ready.
After updating DNS, request a status check, using the actual linked hostname in the path:
curl --fail-with-body --silent --show-error --request POST 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/domains/press.example.com/check' \
--header "Authorization: Bearer $PREZLY_API_TOKEN" \
--header 'Accept: application/json'The response contains domain. The check can activate or deactivate the custom domain based on the DNS result, even though its personal-token scope is sites:read. It is not merely reading a saved status and it is not a DNS-provider write. A previously active domain can become inactive when verification fails.
Inspect status and the instruction validity, then test the intended HTTPS hostname in a browser and re-read the newsroom. Domain status, hosted newsroom availability, and story publication are separate checks. Avoid rapid verification loops or repeatedly linking the same hostname while waiting for DNS to propagate.
Check DNS → · Read saved domain →
Delegate setup instructions without sharing your token
To generate instructions for the intended DNS administrator:
curl --fail-with-body --silent --show-error --request POST 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/domains/press.example.com/share' \
--header "Authorization: Bearer $PREZLY_API_TOKEN" \
--header 'Accept: application/json'The 201 Created response contains sharable_dns_instructions with url and expires_at. This creates a temporary instructions link; it does not send an email. Share the URL only with the intended administrator. It carries limited delegated access, so do not publish it in a public issue, embed it in the website, or treat it as a permanent setup link. Generate another when it expires. Keep your API token separate.
Remove or replace a domain deliberately
DELETE /newsrooms/{newsroom_id}/domains/{domain} unlinks a custom hostname and returns 204 No Content. It does not remove a DNS record from the provider. The Prezly hostname and reverse proxy domains cannot be unlinked through this operation.
Before retiring a hostname, decide where existing links should lead and arrange any required redirects in infrastructure you control. Coordinate removal of stale DNS records with the DNS administrator. Do not promise that unlinking preserves the old hostname's redirects or HTTPS service. If you are replacing a domain, inspect the new instructions again: the recommended target can differ from an older configuration.
After an uncertain link/unlink/check response, read the newsroom's domain list and detail before repeating the operation. A successful API response alone does not establish global DNS propagation or public HTTPS availability.