Skip to content

Check a name's DNS

Check a custom name's current DNS against the records Heaven requires. Supply a Computer to check against the DNS target for its account.

Parameters

#
domainstringRequired
The domain name to check, such as app.example.com, example.com or '*.example.com'.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.
computerstring
Computer whose account supplies the DNS target, by name or ID. Omit to check against the selected account's target.

Returns

#
dataobjectAlways present
Required DNS records and their checks, with HTTPS certificate status.
Show 16 attributesHide attributes
certificateobject
Certificate check for a configured name whose DNS is correct. May be omitted.
Show 2 attributesHide attributes
messagestringAlways present
An explanation of the certificate check.
statestringAlways present
Whether the certificate is ready or still needs attention.
codestring
First problem that needs correction. May be omitted.
computerstring
Organization's Computer currently using this name. May be omitted.
domainstringAlways present
Registrable domain containing the name.
kindstringAlways present
Whether the check concerns an ordinary name, root domain or wildcard.
messagestring
What to change to make the name work. May be omitted.
namestringAlways present
Full name being checked.
one_click_urlstring
A provider page that can add the required records, when supported. May be omitted.
optionalobject[]
Suggested additional records, such as a root domain's www name. May be omitted.
Show 1 attributeHide attributes
itemsobject
One DNS record needed for routing or ownership proof.
Show 7 attributesHide attributes
foundstring
What DNS returned when it differed from the expected value. May be omitted.
namestringAlways present
DNS name where the record belongs.
one_click_urlstring
DNS provider's page for adding this record, when available. May be omitted.
purposestringAlways present
Whether the record establishes routing or proves ownership.
statestringAlways present
DNS-check result. proxied requires turning off Cloudflare's proxy for this record.
typestringAlways present
DNS record type to create.
valuestringAlways present
Value the record should contain.
proofstring
How ownership was proved, such as a CNAME or TXT record. May be omitted.
providerobject
Detected DNS provider and where to edit its records. May be omitted.
Show 4 attributesHide attributes
idstringAlways present
Provider identifier.
namestringAlways present
Provider's display name.
records_urlstring
Provider page for editing DNS records. May be omitted.
root_recordstring
Provider's supported record form for a root domain. May be omitted.
proxiedboolean
Whether Cloudflare's proxy is in front of the name. May be omitted.
recordsobject[] | nullAlways present
Required DNS records and what the check found.
Show 1 attributeHide attributes
itemsobject
One DNS record needed for routing or ownership proof.
Show 7 attributesHide attributes
foundstring
What DNS returned when it differed from the expected value. May be omitted.
namestringAlways present
DNS name where the record belongs.
one_click_urlstring
DNS provider's page for adding this record, when available. May be omitted.
purposestringAlways present
Whether the record establishes routing or proves ownership.
statestringAlways present
DNS-check result. proxied requires turning off Cloudflare's proxy for this record.
typestringAlways present
DNS record type to create.
valuestringAlways present
Value the record should contain.
statestringAlways present
Overall DNS-check result.
targetstringAlways present
Organization's DNS destination.
wholeboolean
Whether the parent domain's DNS already routes this name. May be omitted.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • API key permission: domain check.