Custom domains

API Gateway endpoints can be published on custom domain names (e.g., api.yourdomain.com). Custom domains include automated CNAME verification and TLS certificate management.

Setup workflow

---

Step 1: Claim custom domain in project

Register your custom domain with your project to retrieve your unique CNAME target.

platformctl

platformctl gateway domain claim api.yourdomain.com

Output:

address: api.yourdomain.com
state:   waiting for your DNS record

create this record with your DNS provider:
  type:  CNAME
  name:  api.yourdomain.com
  value: cai-7f3q9k2mx8dw4h1v.gw.codyhill.dev

curl

curl -sS -X POST "$CAI_API/v1/projects/$CAI_PROJECT/gateway/domains" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"domain": "api.yourdomain.com"}'

Expected response (201 Created):

{
  "domain": {
    "domain": "api.yourdomain.com",
    "verified": false,
    "record": {
      "type": "CNAME",
      "name": "api.yourdomain.com",
      "value": "cai-7f3q9k2mx8dw4h1v.gw.codyhill.dev"
    }
  }
}

Console UI

1. Navigate to Networking → Endpoints in the Crusoe Console.
2. Select Custom Domains → Add Domain.
3. Enter api.yourdomain.com and click Add.

---

Step 2: Configure CNAME record at DNS provider

Add a CNAME record with your DNS hosting provider (e.g. Cloudflare, AWS Route53, GoDaddy):

Record Type	Host / Name	Target / Value	Proxy Status
CNAME	api (or api.yourdomain.com)	cai-7f3q9k2mx8dw4h1v.gw.codyhill.dev	DNS Only (Unproxied)

Cloudflare Proxy Configuration

If using Cloudflare, ensure the proxy status is set to DNS Only (Grey Cloud). Proxied records block automated Let's Encrypt TLS validation challenges.

---

Step 3: Publish endpoint on custom domain

Once DNS verification completes, publish your endpoint directly on the custom domain.

platformctl

platformctl gateway publish serverless/hello-world \
  --name support-api --domain api.yourdomain.com

curl

curl -sS -X POST "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "support-api",
    "target": {"kind": "serverless", "name": "hello-world"},
    "domain": {"kind": "custom", "hostname": "api.yourdomain.com"}
  }'

curl -sS -X POST "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api/publish" \
  -H "Authorization: Bearer $CAI_TOKEN"

Console UI

In the Publish Endpoint dialog, select Use Custom Domain and pick api.yourdomain.com from the dropdown list.

---

Domain Lifecycle States

• pending_verification: Waiting for CNAME record propagation.
• programming: CNAME verified; TLS certificate provisioning in progress (~30 seconds).
• ready: Endpoint live over HTTPS on custom domain.
• failed: Verification or certificate failure. Check technical details for resolution steps.