Domains

List Domains

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

Personal Access Token
OAuth: ( domains:read_only)

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 100]
Default: 100

The number of items to return per page.

Request Samples

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

Response Samples

{
  "data": [
    {
      "id": "",
      "status": "active",
      "type": "master",
      "domain": "example.org",
      "group": "",
      "description": "",
      "soa_email": "admin@example.org",
      "retry_sec": 300,
      "master_ips": [],
      "axfr_ips": [],
      "expire_sec": 300,
      "refresh_sec": 300,
      "ttl_sec": 300,
      "tags": [
        "example tag",
        "another example"
      ]
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

200: A paginated list of Domains you have registered.

data
array of objects
id
integer

This Domain's unique ID

status
string
Enum: "disabled""active""edit_mode""has_errors"

Used to control whether this Domain is currently being rendered.

type
string
Enum: "master""slave"

If this Domain represents the authoritative source of information for the domain it describes, or if it is a read-only copy of a master (also called a slave).

domain
Filterable
string([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)

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.

group
Filterable
string
Deprecated

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

description
string

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

soa_email
string

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

retry_sec
integer

The interval, in seconds, at which a failed refresh should be retried. 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.

master_ips
array

The IP addresses representing the master DNS for this Domain.

axfr_ips
array

The list of IPs that may perform a zone transfer for this Domain. This is potentially dangerous, and should be set to an empty list unless you intend to use it.

expire_sec
integer

The amount of time in seconds that may pass before this Domain is no longer authoritative. 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.

refresh_sec
integer

The amount of time in seconds before this Domain should be refreshed. 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.

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 will be rounded to the nearest valid value.
  • ttl_sec will default to 0 if no value is provided.
  • A value of 0 is equivalent to a value of 86400.
tags
Filterable
array

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

page
integer
pages
integer
results
integer

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.

Create Domain

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

Personal Access Token
OAuth: ( domains:read_write)

Request Body Schema

domain
Required
Filterable
string ([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)

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.

type
Required
string
Enum: "master""slave"

If this Domain represents the authoritative source of information for the domain it describes, or if it is a read-only copy of a master (also called a slave).

axfr_ips
array

The list of IPs that may perform a zone transfer for this Domain. This is potentially dangerous, and should be set to an empty list unless you intend to use it.

description
string [1 .. 255] characters

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

expire_sec
integer

The amount of time in seconds that may pass before this Domain is no longer authoritative. 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.

group
Filterable
string [1 .. 50] characters
Deprecated

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

master_ips
array

The IP addresses representing the master DNS for this Domain.

refresh_sec
integer

The amount of time in seconds before this Domain should be refreshed. 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.

retry_sec
integer

The interval, in seconds, at which a failed refresh should be retried. 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.

soa_email
string <email>

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

status
string
Enum: "disabled""active""edit_mode""has_errors"

Used to control whether this Domain is currently being rendered.

tags
Filterable
array

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 will be rounded to the nearest valid value.
  • ttl_sec will default to 0 if no value is provided.
  • A value of 0 is equivalent to a value of 86400.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
        "domain": "example.com",
        "type": "master",
        "soa_email": "admin@example.com",
        "description": "Example Description",
        "refresh_sec": 14400,
        "retry_sec": 3600,
        "expire_sec": 604800,
        "ttl_sec": 3600,
        "status": "active",
        "master_ips": ["127.0.0.1","255.255.255.1","123.123.123.7"],
        "axfr_ips": ["44.55.66.77"],
        "display_group": "Example Display Group"
    }' \
    https://api.linode.com/v4/domains

Response Samples

{
  "id": 1234,
  "status": "active",
  "type": "master",
  "domain": "example.org",
  "group": "",
  "description": "",
  "soa_email": "admin@example.org",
  "retry_sec": 300,
  "master_ips": [],
  "axfr_ips": [],
  "expire_sec": 300,
  "refresh_sec": 300,
  "ttl_sec": 300,
  "tags": []
}

Responses

200: Domain added successfully.

id
integer

This Domain's unique ID

status
string
Enum: "disabled""active""edit_mode""has_errors"

Used to control whether this Domain is currently being rendered.

type
string
Enum: "master""slave"

If this Domain represents the authoritative source of information for the domain it describes, or if it is a read-only copy of a master (also called a slave).

domain
Filterable
string ([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)

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.

group
Filterable
string [1 .. 50] characters
Deprecated

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

description
string [1 .. 255] characters

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

soa_email
string <email>

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

retry_sec
integer

The interval, in seconds, at which a failed refresh should be retried. 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.

master_ips
array of objects

The IP addresses representing the master DNS for this Domain.

axfr_ips
array of objects

The list of IPs that may perform a zone transfer for this Domain. This is potentially dangerous, and should be set to an empty list unless you intend to use it.

expire_sec
integer

The amount of time in seconds that may pass before this Domain is no longer authoritative. 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.

refresh_sec
integer

The amount of time in seconds before this Domain should be refreshed. 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.

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 will be rounded to the nearest valid value.
  • ttl_sec will default to 0 if no value is provided.
  • A value of 0 is equivalent to a value of 86400.
tags
Filterable
array of objects

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

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.