View All Products
Compute
Storage
Databases
Networking
Developer Tools
Delivery
Security
Services
Industries
Pricing
Community
Engage With Us
Linode API 4.163.0

Endpoints

Domains

Domain Record View

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

View a single Record on this Domain.

Path Parameters

domainId
Required
integer

The ID of the Domain whose Record you are accessing.

recordId
Required
integer

The ID of the Record you are accessing.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/domains/123/records/234

Response Samples

{
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "id": 1234,
  "type": "A",
  "port": 80,
  "ttl_sec": 604800,
  "name": "test",
  "target": "192.0.2.0",
  "priority": 50,
  "weight": 50,
  "service": "",
  "protocol": "",
  "tag": ""
}

Responses

200: A Domain Record object.

created
string <date-time>

When this Domain Record was created.

updated
string <date-time>

When this Domain Record was last updated.

id
integer

This Record's unique ID.

type
Filterable
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.

port
integer

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

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.

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. 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).

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. To create a Null MX Record, first remove any additional MX records, 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. Required.

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.

priority
integer

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.

weight
integer

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.

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.

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.

tag
Filterable
Nullable
string
Enum: "issue""issuewild""iodef"

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

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Domain Record Update

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

Updates a single Record on this Domain.

Path Parameters

domainId
Required
integer

The ID of the Domain whose Record you are accessing.

recordId
Required
integer

The ID of the Record you are accessing.

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. 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

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

priority
integer

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. To create a Null MX Record, first remove any additional MX records, 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. Required.

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

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.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X PUT -d '{
      "name": "test",
      "target": "203.0.113.1",
      "priority": 50,
      "weight": 50,
      "port": 80,
      "service": null,
      "protocol": null,
      "ttl_sec": 604800,
      "tag": null
    }' \
    https://api.linode.com/v4/domains/123/records/234

Response Samples

{
  "id": 1234,
  "type": "A",
  "port": 80,
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "ttl_sec": 604800,
  "name": "test",
  "target": "192.0.2.0",
  "priority": 50,
  "weight": 50,
  "service": "",
  "protocol": "",
  "tag": ""
}

Responses

200: Domain Record updated.

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.

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. 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).

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. To create a Null MX Record, first remove any additional MX records, 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. Required.

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.

priority
integer

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.

weight
integer

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.

port
integer

The port this Record points to. Only valid and required 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.

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.

tag
Filterable
Nullable
string
Enum: "issue""issuewild""iodef"

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

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Domain Record Delete

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

Deletes a Record on this Domain.

Path Parameters

domainId
Required
integer

The ID of the Domain whose Record you are accessing.

recordId
Required
integer

The ID of the Record you are accessing.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    -X DELETE \
    https://api.linode.com/v4/domains/123/records/234

Response Samples

{}

Responses

200: Record deleted successfully.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.