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
200andIdempotent-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.