Detect where a domain's DNS lives and how it will be set up
Detect where a domain's DNS lives and how it will be set up: CustomDomain™ API reference in the domains group. Covers parameters, request body and responses.
Read-only feature detection. Returns the provider, the chosen setup_type, whether automatic setup is possible, whether the OAuth-into-provider and one-click setup rails are available, capability flags (ns_support, wildcard_support, cname_flattening, spf_override_support, caa_support), social-login support, any record_conflicts observed in public DNS (records the automatic write would replace), and any advisories (warnings that replace nothing, such as a CAA record that blocks Let's Encrypt). Unknown providers degrade to setup_type: manual.
Apex pre-flight: apex_supported reports whether the provider can host a CNAME-like record at the zone root, and apex_message is returned when this particular target needs one the provider cannot host, so an apex connection that would be refused at apply time is refused here instead, before any connection is created.
The answer is for one application (where its domains point: target_mode and the apex strategy). A widget JWT checks for its own application. An API key checks for application_id, which must be an application in the key's tenant (404 otherwise), or for the key's own application when it is omitted.
rails.cloud_browser (the secure sign-in) is offered only to a caller that could start it, with the reason the start would refuse it with: a widget token bound to no domain, or only to other domains, reads available: false with token_not_bound (mint one with domain and end_user_ref), and an agent, a plain API call without the console or a role that cannot write connections reads caller_cannot_start.
A delegated agent token needs domains:read or domains:connect and checks for its own application; naming another application is a 403.
rails.saved_access lists the kept keys that may act for the domain for the caller, and recommended_rail is then saved_access. An API key gets the workspace's keys. A widget token bound to the domain that names the end user (end_user_ref) gets that end user's own keys, and only when the application allows it (end_user_saved_access), the e-mail that tells them of the reuse can be sent and the key was made at a sign in started with a token minted with their end_user_ref, never at GoDaddy for now (see GET /connections/{id}/saved-access); a miss, for any reason, leaves the other rails as they were, so the end user signs in. The offer is read only: an end user's token cannot use the key yet.
Where the secure sign-in also makes a lasting API key, rails.cloud_browser.key names it before the person signs in: name is the name a key made now would get, before the four character code the sign-in adds at its end (a sign-in makes or reuses a key, so look for a key named like it), delete_url is the provider's own page that deletes keys, and rights and ends_in_days say what it can do and when it ends.
rails.nameservers is the DNS hosting verdict, present while the application offers DNS hosting. verdict and reason say where it goes and why. It is recommended where hosting saves the person the most: four or more records to write (many_records), or no automatic way (no_automatic_way). A root domain whose provider has no record that can point a root is not a reason of its own: a zone CustomDomain™ hosts cannot point a root at a platform that gives no apex addresses either, so hosting is only offered there. On CustomDomain™'s own DNS it falls back to offered with plan_zone_limit once the workspace holds as many hosted zones as its plan counts; nothing is refused.
Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
In: header
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
curl -X POST "https://example.com/domains:check" \ -H "Content-Type: application/json" \ -d '{ "domain": "string" }'{ "domain": "string", "sandbox": true, "subdomain": "string", "registrable_domain": "string", "public_suffix": "string", "provider": "string", "setup_type": "automatic", "supports_automatic": true, "oauth_available": true, "domain_connect": true, "registered": true, "detection_error": "nxdomain", "authoritative_dns_provider": "string", "ns_support": { "root": true, "subdomains": true }, "wildcard_support": true, "cname_flattening": true, "apex_supported": true, "apex_message": "string", "target_mode": "edge", "apex_strategy": "alias", "apex_record_type": "string", "apex_targets": [ "string" ], "spf_override_support": true, "caa_support": true, "supports_social_login": "string", "rails": { "oauth": { "available": true, "reason": "unknown_provider", "caveat": "string", "flow": "oauth2", "managed": true, "regions": [ "eu" ], "key": { "name": "string", "delete_url": "http://example.com", "rights": [ "transfer" ], "ends_in_days": 0 } }, "domain_connect": { "available": true, "reason": "unknown_provider", "caveat": "string", "flow": "oauth2", "managed": true, "regions": [ "eu" ], "key": { "name": "string", "delete_url": "http://example.com", "rights": [ "transfer" ], "ends_in_days": 0 } }, "api_key": { "available": true, "reason": "unknown_provider", "caveat": "string", "flow": "oauth2", "managed": true, "regions": [ "eu" ], "key": { "name": "string", "delete_url": "http://example.com", "rights": [ "transfer" ], "ends_in_days": 0 } }, "manual": { "available": true, "reason": "unknown_provider", "caveat": "string", "flow": "oauth2", "managed": true, "regions": [ "eu" ], "key": { "name": "string", "delete_url": "http://example.com", "rights": [ "transfer" ], "ends_in_days": 0 } }, "cloud_browser": { "available": true, "reason": "unknown_provider", "caveat": "string", "flow": "oauth2", "managed": true, "regions": [ "eu" ], "key": { "name": "string", "delete_url": "http://example.com", "rights": [ "transfer" ], "ends_in_days": 0 } }, "nameservers": { "verdict": "offered", "reason": "application_offers" }, "saved_access": { "available": true, "accounts": [ { "account_id": "string", "provider": "string", "provider_name": "string", "label": "string", "how": "api_key", "owner_kind": "workspace", "scope": "all", "zone": "string", "ready": true, "status": "active", "application_id": "string", "key_name": "string", "key_expires_at": "2019-08-24T14:15:22Z", "last_used_at": "2019-08-24T14:15:22Z", "from_domain": "string" } ] } }, "also_provider": { "provider": "string", "provider_name": "string", "reason": "former_google_domains" }, "recommended_rail": "saved_access", "end_user_automatic": true, "blocked_reason": "unregistered", "dashboard_url": "string", "nameservers": [ "string" ], "managed_dns": { "available": true, "reason": "" }, "nameserver_migration": { "mode": "offer", "target": "managed", "dns_host": "string", "available": true, "reason": "disabled", "path": "agent", "provider": "string", "registrar": { "name": "string", "provider": "string", "iana_id": 0, "url": "string", "source": "rdap" }, "nameservers": [ "string" ] }, "integration_warnings": [ { "code": "supplied_apex_unrealizable", "message": "string" } ], "record_conflicts": [ { "kind": "string", "host": "string", "type": "string", "existing": "string", "desired": "string" } ], "advisories": [ { "kind": "string", "host": "string", "type": "string", "existing": "string", "desired": "string" } ], "conflict_tolerance": 0, "will_fallback_to_manual": true}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}