Skip to content

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 ​

text
Register the domain www.example.com on Edge and tell me which DNS
records I need to create.
bash
edge api POST /v1/domains --input - <<'EOF'
{ "fqdn": "www.example.com" }
EOF
bash
curl -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 ​

text
I have added the DNS records. Verify www.example.com.
bash
edge api POST /v1/domains/www.example.com/verify
bash
curl -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 ​

text
Attach www.example.com to the acme-marketing distribution.
bash
edge api POST /v1/domains/www.example.com/attach --input - <<'EOF'
{ "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38" }
EOF
bash
curl -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 ​

text
Poll www.example.com until it is active and tell me when it is serving.
bash
edge api GET /v1/domains/www.example.com
bash
curl -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:

text
Detach www.example.com from its distribution, but keep the domain registered.
bash
edge api POST /v1/domains/www.example.com/detach
bash
curl -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 ​