DocumentationAPI reference

API reference

The Custom Domain API v1 reference. Register customer hostnames, read their DNS records and checks, re-check and delete them, with idempotency, pagination, errors, limits and how bandwidth is counted.

Base URL: https://edge.customdomainapi.com/v1 on Free; on a paid or self-hosted edge, https://<your edge name>/v1.

Authentication: every request sends your API key:

Authorization: Bearer cd_...

The application is derived from the key, never from a request field. Keys are not accepted in query strings or cookies.

Machine-readable contract: the OpenAPI document is at /v1/openapi.json on every edge, and in the repository as docs/openapi.json.

Endpoints

Method and path Purpose Success
POST /v1/domains Register a hostname for a workspace. 201, or 200 on an idempotent replay
GET /v1/domains List domains. Filters: reference, status, include_deleted. Pages: limit (1 to 200, default 50), offset. 200
GET /v1/domains/{id} One domain with its current checks. 200
POST /v1/domains/{id}/checks Re-run all checks now. 202
DELETE /v1/domains/{id} Stop serving and delete. 202
POST /v1/webhooks Subscribe to events (Webhooks). 201
GET /v1/webhooks List subscriptions. 200
POST /v1/webhooks/{id}/rotate New signing secret. 200
DELETE /v1/webhooks/{id} Revoke a subscription. 200

Register a domain

POST /v1/domains
Authorization: Bearer cd_...
Idempotency-Key: signup-ws_8f3a1c
Content-Type: application/json

{"hostname": "forms.acme.com", "reference": "ws_8f3a1c", "metadata": {"plan": "pro"}}
  • hostname: the customer’s exact subdomain. It’s normalized to lowercase punycode. Apex domains (acme.com), wildcards and IP addresses are refused.
  • reference: your opaque workspace id (up to 255 characters). It is returned verbatim and delivered to your origin in the assertion.
  • metadata: optional, up to 32 scalar values, echoed back.

Response 201:

{
  "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
  "hostname": "forms.acme.com",
  "reference": "ws_8f3a1c",
  "status": "pending_dns",
  "dns_records": [
    {"name": "_custom-domain-challenge.forms.acme.com", "type": "TXT",
     "value": "custom-domain-verify=…", "purpose": "ownership", "help": "…"},
    {"name": "forms.acme.com", "type": "CNAME",
     "value": "edge.customdomainapi.com", "purpose": "routing", "help": "…"}
  ],
  "checks": [
    {"type": "ownership", "status": "pending", "error_code": null, "message": null,
     "observed_at": null, "next_check_at": null},
    {"type": "routing", "status": "pending"},
    {"type": "certificate", "status": "pending"},
    {"type": "origin", "status": "pending"}
  ],
  "metadata": {"plan": "pro"},
  "created_at": "2026-10-04T14:00:00Z",
  "updated_at": "2026-10-04T14:00:00Z",
  "deleted_at": null
}

Show both dns_records to your customer exactly as returned. Statuses and checks are explained in How it works.

Idempotency

Send Idempotency-Key (up to 255 characters, unique per application) on POST /v1/domains, and retries are safe:

  • the same key and body returns the first result with 200 and Idempotent-Replayed: true;
  • the same key with a different body is 422 idempotency_key_reused;
  • a retry while the first is still running is 409 idempotency_request_in_progress;
  • keys expire after 24 hours.

Errors

Every error has the same shape:

{"error": {"code": "hostname_already_claimed", "message": "forms.acme.com is already claimed", "details": {}}}
Status code When
401 unauthorized Missing, unknown, revoked or expired key.
403 application_suspended Your application is suspended.
404 domain_not_found No such domain in your application. Another application’s domains are never visible.
409 hostname_already_claimed The hostname is live in this or another application.
409 domain_limit_reached Your application is at its domain limit (25 on Free). Existing domains keep working.
409 invalid_status_transition Not possible in the domain’s status, such as re-checking a deleted domain.
409 idempotency_request_in_progress The first request with this key hasn’t finished.
422 validation_error The body or query doesn’t match the schema; details.errors lists where.
422 apex_not_supported, wildcard_not_supported, ip_literal_not_supported, invalid_hostname, invalid_label, hostname_too_long, empty_hostname The hostname can’t be registered.
422 invalid_reference The reference is empty or longer than 255 characters.
422 idempotency_key_reused The key was used with a different body.
429 rate_limited Too many requests; wait Retry-After seconds.

Limits on Free

Limit Value
Customer hostnames 25
API keys 1 (two during a rotation’s 24-hour overlap)
API requests 60 a minute per key
Proxied requests 600 a minute and 100 a second, across all your hostnames; over either, visitors get 429 with Retry-After
Manual re-checks 1 per domain a minute, 60 per application an hour
Bandwidth 100 GB a month (UTC calendar month) of response bodies sent to visitors; headers and request bodies don’t count
Above 100 GB Proxied requests are limited to 60 a minute and 5 a second until the month ends; over either, 429 with Retry-After. We email you at 80% and at 100%. Nothing is billed, deleted or switched off.

Paid plans have their own edge, with more domains, 1 TB to 20 TB of bandwidth a month (then $0.05 per GB) and no proxied-request limit of ours.

Bandwidth

Bandwidth is the response bodies the edge sends to visitors; request bodies and headers don’t count. 1 GB is 1,000,000,000 bytes and 1 TB is 1,000 GB. The edge counts response bodies per hostname, from its own counters, and they are added up per application and UTC day. A few minutes of traffic around an edge restart or a change to its configuration may go uncounted; nothing is counted twice.

Plan Included each month Above the allowance
Free 100 GB, per UTC calendar month Not billed: proxied requests are limited to 60 a minute and 5 a second until the month ends
Starter 1 TB $0.05 per whole GB
Growth 10 TB $0.05 per whole GB
Scale 20 TB $0.05 per whole GB

On a paid edge, all its applications share the plan’s allowance. A billing period counts the UTC days from its start date up to, but not including, its end date, so every day counts in exactly one period. What is above the allowance is billed per whole GB, rounded down. On a yearly plan, extra bandwidth and extra domains are billed monthly, on a separate invoice.

SDK

The Python SDK wraps all of the above, with typed errors and safe retries:

pip install custom-domain-sdk

See the SDK README.