Domains v4.173.0

Domains List

GET https://api.linode.com/v4/domains

This is a collection of Domains that you have registered in Linode’s DNS Manager. Linode is not a registrar, and in order for these to work you must own the domains and point your registrar at Linode’s nameservers.

Authorizations

personalAccessToken
oauthdomains:read_only

Query Parameters

page
Type:
integer >= 1
Default: 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..500
Default: 100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Domain Create

POST https://api.linode.com/v4/domains

Adds a new Domain to Linode’s DNS Manager. Linode is not a registrar, and you must own the domain before adding it here. Be sure to point your registrar to Linode’s nameservers so that the records hosted here are used.

Authorizations

personalAccessToken
oauthdomains:read_write

Request Samples

Request Body Schema

axfr_ips
array of strings

The list of IPs that may perform a zone transfer for this Domain. The total combined length of all data within this array cannot exceed 1000 characters.

Note: This is potentially dangerous, and should be set to an empty list unless you intend to use it.

description
string 1..253 characters

A description for this Domain. This is for display purposes only.

domain
Filterable
Required
string 1..253 characters

The domain this Domain represents. Domain labels cannot be longer than 63 characters and must conform to RFC1035. Domains must be unique on Linode’s platform, including across different Linode accounts; there cannot be two Domains representing the same domain.

expire_sec
integer

The amount of time in seconds that may pass before this Domain is no longer authoritative.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 1209600.

group
Filterable
string 1..50 characters

The group this Domain belongs to. This is for display purposes only.

master_ips
array of strings

The IP addresses representing the master DNS for this Domain. At least one value is required for type slave Domains. The total combined length of all data within this array cannot exceed 1000 characters.

refresh_sec
integer

The amount of time in seconds before this Domain should be refreshed.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 14400.

retry_sec
integer

The interval, in seconds, at which a failed refresh should be retried.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 14400.

soa_email
string<email>

Start of Authority email address. This is required for type master Domains.

status
string
Enum: disabled active Default: active

Used to control whether this Domain is currently being rendered.

tags
Filterable
array of strings

An array of tags applied to this object. Tags are for organizational purposes only.

ttl_sec
integer

“Time to Live” - the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
  • Any other value is rounded up to the nearest valid value.
  • A value of 0 is equivalent to the default value of 86400.

type
Required
string
Enum: master slave

Whether this Domain represents the authoritative source of information for the domain it describes (“master”), or whether it is a read-only copy of a master (“slave”).

Response Samples

Responses

Domain Import

POST https://api.linode.com/v4/domains/import

Imports a domain zone from a remote nameserver. Your nameserver must allow zone transfers (AXFR) from the following IPs:

  • 96.126.114.97
  • 96.126.114.98
  • 2600:3c00::5e
  • 2600:3c00::5f

Authorizations

personalAccessToken
oauthdomains:read_write

Request Samples

Request Body Schema

domain
Required
string

The domain to import.

remote_nameserver
Required
string

The remote nameserver that allows zone transfers (AXFR).

Response Samples

Responses

Domain Delete

DELETE https://api.linode.com/v4/domains/{domainId}

Deletes a Domain from Linode’s DNS Manager. The Domain will be removed from Linode’s nameservers shortly after this operation completes. This also deletes all associated Domain Records.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdinteger
Required

The ID of the Domain to access.

Request Samples

Response Samples

Responses

Domain View

GET https://api.linode.com/v4/domains/{domainId}

This is a single Domain that you have registered in Linode’s DNS Manager. Linode is not a registrar, and in order for this Domain record to work you must own the domain and point your registrar at Linode’s nameservers.

Authorizations

personalAccessToken
oauthdomains:read_only

Path Parameters

domainIdinteger
Required

The ID of the Domain to access.

Request Samples

Response Samples

Responses

Domain Update

PUT https://api.linode.com/v4/domains/{domainId}

Update information about a Domain in Linode’s DNS Manager.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdinteger
Required

The ID of the Domain to access.

Request Samples

Request Body Schema

axfr_ips
array of strings

The list of IPs that may perform a zone transfer for this Domain. The total combined length of all data within this array cannot exceed 1000 characters.

Note: This is potentially dangerous, and should be set to an empty list unless you intend to use it.

description
string 1..253 characters

A description for this Domain. This is for display purposes only.

domain
Filterable
string 1..253 characters

The domain this Domain represents. Domain labels cannot be longer than 63 characters and must conform to RFC1035. Domains must be unique on Linode’s platform, including across different Linode accounts; there cannot be two Domains representing the same domain.

expire_sec
integer

The amount of time in seconds that may pass before this Domain is no longer authoritative.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 1209600.

group
Filterable
string 1..50 characters

The group this Domain belongs to. This is for display purposes only.

master_ips
array of strings

The IP addresses representing the master DNS for this Domain. At least one value is required for type slave Domains. The total combined length of all data within this array cannot exceed 1000 characters.

refresh_sec
integer

The amount of time in seconds before this Domain should be refreshed.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 14400.

retry_sec
integer

The interval, in seconds, at which a failed refresh should be retried.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.

  • Any other value is rounded up to the nearest valid value.

  • A value of 0 is equivalent to the default value of 14400.

soa_email
string<email>

Start of Authority email address. This is required for type master Domains.

status
string
Enum: disabled active Default: active

Used to control whether this Domain is currently being rendered.

tags
Filterable
array of strings

An array of tags applied to this object. Tags are for organizational purposes only.

ttl_sec
integer

“Time to Live” - the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers.

  • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
  • Any other value is rounded up to the nearest valid value.
  • A value of 0 is equivalent to the default value of 86400.

type
string
Enum: master slave

Whether this Domain represents the authoritative source of information for the domain it describes (“master”), or whether it is a read-only copy of a master (“slave”).

Response Samples

Responses

Domain Clone

POST https://api.linode.com/v4/domains/{domainId}/clone

Clones a Domain and all associated DNS records from a Domain that is registered in Linode’s DNS manager.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdstring
Required

ID of the Domain to clone.

Request Samples

Request Body Schema

domain
Filterable
Required
string 1..253 characters

The new domain for the clone. Domain labels cannot be longer than 63 characters and must conform to RFC1035. Domains must be unique on Linode’s platform, including across different Linode accounts; there cannot be two Domains representing the same domain.

Response Samples

Responses

Domain Records List

GET https://api.linode.com/v4/domains/{domainId}/records

Returns a paginated list of Records configured on a Domain in Linode’s DNS Manager.

Authorizations

personalAccessToken
oauthdomains:read_only

Path Parameters

domainIdinteger
Required

The ID of the Domain we are accessing Records for.

Query Parameters

page
Type:
integer >= 1
Default: 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..500
Default: 100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Domain Record Create

POST https://api.linode.com/v4/domains/{domainId}/records

Adds a new Domain Record to the zonefile this Domain represents.

Each domain can have up to 12,000 active records.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdinteger
Required

The ID of the Domain we are accessing Records for.

Request Samples

Request Body Schema

name
Filterable
string 1..100 characters

The name of this Record. For requests, this property’s actual usage and whether it is required depends on the type of record this represents:

A and AAAA: The hostname or FQDN of the Record.

NS: The subdomain, if any, to use with the Domain of the Record. Wildcard NS records (*) are not supported.

MX: The mail subdomain. For example, sub for the address user@sub.example.com under the example.com Domain.

  • The left-most subdomain component may be an asterix (*) to designate a wildcard subdomain.
  • Other subdomain components must only contain letters, digits, and hyphens, start with a letter, end with a letter or digit, and contain less than 64 characters.
  • Must be an empty string ("") for a Null MX Record.

CNAME: The hostname. Must be unique. Required.

TXT: The hostname.

SRV: Unused. Use the service property to set the service name for this record.

CAA: The subdomain. Omit or enter an empty string ("") to apply to the entire Domain.

PTR: See our guide on how to Configure Your Linode for Reverse DNS (rDNS).

port
integer 0..65535

The port this Record points to. Only valid and required for SRV record requests.

priority
integer 0..255

The priority of the target host for this Record. Lower values are preferred. Only valid for MX and SRV record requests. Required for SRV record requests.

Defaults to 0 for MX record requests. Must be 0 for Null MX records.

protocol
Nullable
string

The protocol this Record’s service communicates with. An underscore (_) is prepended automatically to the submitted value for this property. Only valid for SRV record requests.

service
Nullable
string

The name of the service. An underscore (_) is prepended and a period (.) is appended automatically to the submitted value for this property. Only valid and required for SRV record requests.

tag
Filterable
Nullable
string
Enum: issue issuewild iodef

The tag portion of a CAA record. Only valid and required for CAA record requests.

target
Filterable
string <= 65535 characters

The target for this Record. For requests, this property’s actual usage and whether it is required depends on the type of record this represents:

A and AAAA: The IP address. Use [remote_addr] to submit the IPv4 address of the request. Required.

NS: The name server. Must be a valid domain. Required.

MX: The mail server. Must be a valid domain unless creating a Null MX Record. Required.

  • Must have less than 254 total characters.
  • The left-most domain component may be an asterix (*) to designate a wildcard domain.
  • Other domain components must only contain letters, digits, and hyphens, start with a letter, end with a letter or digit, and contain less than 64 characters.
  • To create a Null MX Record, first remove any additional MX records, then create an MX record with empty strings ("") for the target and name. If a Domain has a Null MX record, new MX records cannot be created.

CNAME: The alias. Must be a valid domain. Required.

TXT: The value. Required.

SRV: The target domain or subdomain. If a subdomain is entered, it is automatically used with the Domain. To configure for a different domain, enter a valid FQDN. For example, the value www with a Domain for example.com results in a target set to www.example.com, whereas the value sample.com results in a target set to sample.com. Required.

CAA: The value. For issue or issuewild tags, the domain of your certificate issuer. For the iodef tag, a contact or submission URL (domain, http, https, or mailto). Requirements depend on the tag for this record:

  • issue: The domain of your certificate issuer. Must include a valid domain. May include additional parameters separated with semicolons (;), for example: www.example.com; foo=bar
  • issuewild: The domain of your wildcard certificate issuer. Must be a valid domain and must not start with an asterisk (*).
  • iodef: Must be either (1) a valid domain, (2) a valid domain prepended with http:// or https://, or (3) a valid email address prepended with mailto:.

PTR: Required. See our guide on how to Configure Your Linode for Reverse DNS (rDNS).

With the exception of A, AAAA, and CAA records, this field accepts a trailing period.

ttl_sec
integer

“Time to Live” - the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. Valid values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.

type
Filterable
Required
string
Enum: A AAAA NS MX CNAME TXT SRV PTR CAA

The type of Record this is in the DNS system. For example, A records associate a domain name with an IPv4 address, and AAAA records associate a domain name with an IPv6 address. For more information, see the guides on DNS Record Types.

weight
integer 0..65535

The relative weight of this Record used in the case of identical priority. Higher values are preferred. Only valid and required for SRV record requests.

Response Samples

Responses

Domain Record Delete

DELETE https://api.linode.com/v4/domains/{domainId}/records/{recordId}

Deletes a Record on this Domain.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdinteger
Required

The ID of the Domain whose Record you are accessing.

recordIdinteger
Required

The ID of the Record you are accessing.

Request Samples

Response Samples

Responses

Domain Record View

GET https://api.linode.com/v4/domains/{domainId}/records/{recordId}

View a single Record on this Domain.

Authorizations

personalAccessToken
oauthdomains:read_only

Path Parameters

domainIdinteger
Required

The ID of the Domain whose Record you are accessing.

recordIdinteger
Required

The ID of the Record you are accessing.

Request Samples

Response Samples

Responses

Domain Record Update

PUT https://api.linode.com/v4/domains/{domainId}/records/{recordId}

Updates a single Record on this Domain.

Authorizations

personalAccessToken
oauthdomains:read_write

Path Parameters

domainIdinteger
Required

The ID of the Domain whose Record you are accessing.

recordIdinteger
Required

The ID of the Record you are accessing.

Request Samples

Request Body Schema

name
Filterable
string 1..100 characters

The name of this Record. For requests, this property’s actual usage and whether it is required depends on the type of record this represents:

A and AAAA: The hostname or FQDN of the Record.

NS: The subdomain, if any, to use with the Domain of the Record. Wildcard NS records (*) are not supported.

MX: The mail subdomain. For example, sub for the address user@sub.example.com under the example.com Domain.

  • The left-most subdomain component may be an asterix (*) to designate a wildcard subdomain.
  • Other subdomain components must only contain letters, digits, and hyphens, start with a letter, end with a letter or digit, and contain less than 64 characters.
  • Must be an empty string ("") for a Null MX Record.

CNAME: The hostname. Must be unique. Required.

TXT: The hostname.

SRV: Unused. Use the service property to set the service name for this record.

CAA: The subdomain. Omit or enter an empty string ("") to apply to the entire Domain.

PTR: See our guide on how to Configure Your Linode for Reverse DNS (rDNS).

port
integer 0..65535

The port this Record points to. Only valid and required for SRV record requests.

priority
integer 0..255

The priority of the target host for this Record. Lower values are preferred. Only valid for MX and SRV record requests. Required for SRV record requests.

Defaults to 0 for MX record requests. Must be 0 for Null MX records.

protocol
Nullable
string

The protocol this Record’s service communicates with. An underscore (_) is prepended automatically to the submitted value for this property. Only valid for SRV record requests.

service
Nullable
string

The name of the service. An underscore (_) is prepended and a period (.) is appended automatically to the submitted value for this property. Only valid and required for SRV record requests.

tag
Filterable
Nullable
string
Enum: issue issuewild iodef

The tag portion of a CAA record. Only valid and required for CAA record requests.

target
Filterable
string <= 65535 characters

The target for this Record. For requests, this property’s actual usage and whether it is required depends on the type of record this represents:

A and AAAA: The IP address. Use [remote_addr] to submit the IPv4 address of the request. Required.

NS: The name server. Must be a valid domain. Required.

MX: The mail server. Must be a valid domain unless creating a Null MX Record. Required.

  • Must have less than 254 total characters.
  • The left-most domain component may be an asterix (*) to designate a wildcard domain.
  • Other domain components must only contain letters, digits, and hyphens, start with a letter, end with a letter or digit, and contain less than 64 characters.
  • To create a Null MX Record, first remove any additional MX records, then create an MX record with empty strings ("") for the target and name. If a Domain has a Null MX record, new MX records cannot be created.

CNAME: The alias. Must be a valid domain. Required.

TXT: The value. Required.

SRV: The target domain or subdomain. If a subdomain is entered, it is automatically used with the Domain. To configure for a different domain, enter a valid FQDN. For example, the value www with a Domain for example.com results in a target set to www.example.com, whereas the value sample.com results in a target set to sample.com. Required.

CAA: The value. For issue or issuewild tags, the domain of your certificate issuer. For the iodef tag, a contact or submission URL (domain, http, https, or mailto). Requirements depend on the tag for this record:

  • issue: The domain of your certificate issuer. Must include a valid domain. May include additional parameters separated with semicolons (;), for example: www.example.com; foo=bar
  • issuewild: The domain of your wildcard certificate issuer. Must be a valid domain and must not start with an asterisk (*).
  • iodef: Must be either (1) a valid domain, (2) a valid domain prepended with http:// or https://, or (3) a valid email address prepended with mailto:.

PTR: Required. See our guide on how to Configure Your Linode for Reverse DNS (rDNS).

With the exception of A, AAAA, and CAA records, this field accepts a trailing period.

ttl_sec
integer

“Time to Live” - the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. Valid values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.

weight
integer 0..65535

The relative weight of this Record used in the case of identical priority. Higher values are preferred. Only valid and required for SRV record requests.

Response Samples

Responses

Domain Zone File View

GET https://api.linode.com/v4/domains/{domainId}/zone-file

Returns the zone file for the last rendered zone for the specified domain.

Authorizations

personalAccessToken
oauthdomains:read_only

Path Parameters

domainIdstring
Required

ID of the Domain.

Request Samples

Response Samples

Responses