Skip to content

Add a name to a Computer

Assign a custom hostname, apex domain or wildcard to a Computer's website. Heaven serves a new name after DNS verification and removes names that remain unverified for seven days. A name that serves the website uses the Computer's website access settings. Use domain check to see which DNS records the name needs.

Parameters

#
computerstringRequired
Computer name or ID.
domainstringRequired
Hostname, apex domain or wildcard you control, such as www.example.com, example.com or *.example.com. For path, give the existing website name.
portstring
HTTP port inside the Computer for this hostname or path, from 1 to 65535 except the desktop port 6080. Omit to use the Computer's website port. Use only for a route without redirect.
redirectstring
HTTPS destination for a redirect from this name. Supply the URL or hostname. Use only when both port and path are omitted. The redirect runs before the Computer's website access check.
pathstring
Path prefix such as /api on an already verified website name in the same organization. Routes that part of the website to another Computer. Use strip_prefix: true to remove the prefix before forwarding.
strip_prefixboolean
Remove the path prefix before forwarding. For example, with path /api, the Computer receives /users for /api/users. Requires path.

Returns

#
dataobjectAlways present
A saved domain assignment or removal.
Show 11 attributesHide attributes
alsostring[]
Other names changed with this one, such as www. May be omitted.
computerstringAlways present
Computer associated with the change.
domainstringAlways present
Affected domain name.
moved_fromstring
Computer that previously held the name. May be omitted.
pathstring
Affected path prefix, for a path route. May be omitted.
portinteger
Selected guest port, when explicitly set. May be omitted.
redirectstring
Configured redirect destination. May be omitted.
removedboolean
Whether the assignment was removed. May be omitted.
setupobject
DNS check explaining what remains to be configured. May be omitted.
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.
updatedbooleanAlways present
Whether the assignment was updated.
waitingboolean
Whether DNS proof is pending. The saved name serves only after proof succeeds. 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.
payment_required402Payment or credit is required.
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 add.