Attach a custom domain
Every distribution is reachable at your-slug.edge.deca-dev.com from the moment it goes live. This page puts it on a hostname you own, such as www.example.com.
Each step shows both ways of working: describing the task to an agent, using the CLI, or calling the API yourself. Creating the DNS records in the middle is yours either way — an agent cannot reach into your DNS provider.
Before you start
You need the ability to add DNS records for the domain.
Domains are not managed from the web console. The Domains page at https://app.edge.deca-dev.com/edge/{workspaceId}/domains lists them and shows their status, which is useful while you work through the steps below, but the actions are API-only.
1. Register the domain
Register the domain www.example.com on Edge and tell me which DNS
records I need to create.edge api POST /v1/domains --input - <<'EOF'
{ "fqdn": "www.example.com" }
EOFcurl -s -X POST https://api.edge.deca-dev.com/v1/domains \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "fqdn": "www.example.com" }'The response tells you which DNS records to create, including a TXT record that proves you control the name.
Agent equivalent:
edge_domain_create
2. Create the DNS records
At your DNS provider, add the TXT record from step 1, plus the A/AAAA or CNAME record it specifies pointing at Edge.
Give them time to propagate before continuing. Verification checks what your DNS actually returns, so a record that has not propagated yet reads as absent.
3. Verify
I have added the DNS records. Verify www.example.com.edge api POST /v1/domains/www.example.com/verifycurl -s -X POST https://api.edge.deca-dev.com/v1/domains/www.example.com/verify \
-H "Authorization: Bearer $EDGE_TOKEN"If this fails, the TXT record is not visible yet. Wait and try again rather than recreating the domain.
Agent equivalent:
edge_domain_verify
4. Attach it to a distribution
Attach www.example.com to the acme-marketing distribution.edge api POST /v1/domains/www.example.com/attach --input - <<'EOF'
{ "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38" }
EOFcurl -s -X POST https://api.edge.deca-dev.com/v1/domains/www.example.com/attach \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38" }'A domain must be verified before it can be attached; attaching an unverified domain returns 409.
Agent equivalent:
edge_domain_attach
5. Wait for it to go active
Poll www.example.com until it is active and tell me when it is serving.edge api GET /v1/domains/www.example.comcurl -s https://api.edge.deca-dev.com/v1/domains/www.example.com \
-H "Authorization: Bearer $EDGE_TOKEN"Poll until status is active. A certificate is issued during this step, so it is not instant. If status becomes failed, the response says what went wrong.
Once active, your distribution serves on https://www.example.com. The your-slug.edge.deca-dev.com address keeps working.
Agent equivalent:
edge_domain_get
Detaching and removing
To stop serving a distribution on the domain while keeping the domain registered:
Detach www.example.com from its distribution, but keep the domain registered.edge api POST /v1/domains/www.example.com/detachcurl -s -X POST https://api.edge.deca-dev.com/v1/domains/www.example.com/detach \
-H "Authorization: Bearer $EDGE_TOKEN"To remove it entirely, DELETE /v1/domains/www.example.com with the fqdn repeated in the body as confirm_fqdn. That confirmation is deliberate — deleting a domain takes a live hostname out of service.
Things that will trip you up
- Preview URLs never use custom domains. A deployment preview is always on
*.preview.edge.deca-dev.com, whatever domains the distribution has. - Verification is not permanent proof. Leave the TXT record in place.
- Domain creation is rate limited to 10 per hour per workspace, and a distribution can hold at most 10 domains. Repeated attempts return 429; wait rather than retrying in a loop. See Limits.
Next
- Patch, promote, and roll back
- Errors — what each status code means