Custom Domains
Custom-domain setup, DNS and certificate status, setup lifecycle, and next actions for the Platform API.
The Custom Domains API reports account setup, attached-domain status, observed DNS values, managed certificate status, and lifecycle guidance. certificateStatus reports issuance state; certificateActive reports whether the issued certificate is attached to serve the custom domains. dnsValue is the DNS value currently observed; cnameValue is the target to configure. DNS records are managed by the account’s DNS provider. An empty domains list means no customer domains are attached.
Every setup response includes setupStatus: a state, human-readable message, recommended nextAction, domains blocking DNS progress, and an isReady flag. Reading the setup status also advances certificate setup, so polling status is enough to reach READY after DNS is configured.
| State | Meaning | Next action |
|---|---|---|
NO_DOMAINS | No customer domains are attached. | ADD_DOMAINS |
DNS_REQUIRED | One or more domains do not point to the required CNAME. blockingDomains names them. | CONFIGURE_DNS |
CERTIFICATE_VALIDATION_REQUIRED | DNS is configured and certificate validation is waiting for DNS changes to reach the CDN. | RECONCILE_CERTIFICATE |
CERTIFICATE_PENDING | Certificate issuance is in progress. | WAIT |
CERTIFICATE_ACTIVATION_REQUIRED | The certificate is issued and is activated on the next status read. | RECONCILE_CERTIFICATE |
DEPLOYING | The certificate is active and the domain configuration is deploying. | WAIT |
READY | All domains are ready to serve HTTPS traffic. | NONE |
CERTIFICATE_FAILED | Certificate setup failed or the certificate is no longer valid. | CONTACT_SUPPORT |
DISABLED | Custom-domain serving is disabled for the account. | CONTACT_SUPPORT |
Reading the setup status starts certificate validation once DNS is configured and activates the certificate once it is issued. The certificate-validation operation does the same on demand; when nextAction is RECONCILE_CERTIFICATE, call it to retry immediately instead of waiting for the next status read. If DNS changes have not reached the CDN yet, it returns HTTP 409; wait a few minutes and retry.
GET/rest/v1/custom-domains/setup
Ours Privacy API key
In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/rest/v1/custom-domains/setup"{ "setup": { "id": "string", "enabled": true, "status": "string", "createdAt": "string", "updatedAt": "string", "setupStatus": { "state": "NO_DOMAINS", "message": "string", "nextAction": "ADD_DOMAINS", "blockingDomains": [ "string" ], "isReady": true }, "certificateStatus": "string", "certificateActive": true, "domains": [ { "domain": "string", "status": "active", "dnsStatus": "configured", "dnsValue": "string", "cnameValue": "string" } ] }}POST/rest/v1/custom-domains
Ours Privacy API key
In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/rest/v1/custom-domains"{ "setup": { "id": "string", "enabled": true, "status": "string", "createdAt": "string", "updatedAt": "string", "setupStatus": { "state": "NO_DOMAINS", "message": "string", "nextAction": "ADD_DOMAINS", "blockingDomains": [ "string" ], "isReady": true }, "certificateStatus": "string", "certificateActive": true, "domains": [ { "domain": "string", "status": "active", "dnsStatus": "configured", "dnsValue": "string", "cnameValue": "string" } ] }}PUT/rest/v1/custom-domains/{id}
Ours Privacy API key
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/rest/v1/custom-domains/string" \ -H "Content-Type: application/json" \ -d '{ "domains": [ "string" ] }'{ "setup": { "id": "string", "enabled": true, "status": "string", "createdAt": "string", "updatedAt": "string", "setupStatus": { "state": "NO_DOMAINS", "message": "string", "nextAction": "ADD_DOMAINS", "blockingDomains": [ "string" ], "isReady": true }, "certificateStatus": "string", "certificateActive": true, "domains": [ { "domain": "string", "status": "active", "dnsStatus": "configured", "dnsValue": "string", "cnameValue": "string" } ] }}POST/rest/v1/custom-domains/{id}/certificate-validation
Ours Privacy API key
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/rest/v1/custom-domains/string/certificate-validation"{ "setup": { "id": "string", "enabled": true, "status": "string", "createdAt": "string", "updatedAt": "string", "setupStatus": { "state": "NO_DOMAINS", "message": "string", "nextAction": "ADD_DOMAINS", "blockingDomains": [ "string" ], "isReady": true }, "certificateStatus": "string", "certificateActive": true, "domains": [ { "domain": "string", "status": "active", "dnsStatus": "configured", "dnsValue": "string", "cnameValue": "string" } ] }}How is this guide?