Give Feedback

Domain Records

Validated on 19 Jun 2018 • Last edited on 23 Mar 2026

Domain record resources are used to set or retrieve information about the individual DNS records configured for a domain. This allows you to build and manage DNS zone files by adding and modifying individual records for a domain.

The DigitalOcean DNS management interface allows you to configure the following DNS records:

Name	Description
A	This record type is used to map an IPv4 address to a hostname.
AAAA	This record type is used to map an IPv6 address to a hostname.
CAA	As specified in RFC-6844, this record type can be used to restrict which certificate authorities are permitted to issue certificates for a domain.
CNAME	This record type defines an alias for your canonical hostname (the one defined by an A or AAAA record).
MX	This record type is used to define the mail exchanges used for the domain.
NS	This record type defines the name servers that are used for this zone.
TXT	This record type is used to associate a string of text with a hostname, primarily used for verification.
SRV	This record type specifies the location (hostname and port number) of servers for specific services.
SOA	This record type defines administrative information about the zone. Can only have ttl changed, cannot be deleted

Base URL https://api.digitalocean.com

Endpoints

GET List All Domain Records POST Create a New Domain Record GET Retrieve an Existing Domain Record PUT Update a Domain Record PATCH Update a Domain Record DELETE Delete a Domain Record

GET List All Domain Records

/v2/domains/{domain_name}/records

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To get a listing of all records configured for a domain, send a GET request to /v2/domains/$DOMAIN_NAME/records. The list of records returned can be filtered by using the name and type query parameters. For example, to only include A records for a domain, send a GET request to /v2/domains/$DOMAIN_NAME/records?type=A. name must be a fully qualified record name. For example, to only include records matching sub.example.com, send a GET request to /v2/domains/$DOMAIN_NAME/records?name=sub.example.com. Both name and type may be used together.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

Query Parameters

name string optional

Example: sub.example.com

A fully qualified record name. For example, to only include records matching sub.example.com, send a GET request to /v2/domains/$DOMAIN_NAME/records?name=sub.example.com.

type string (enum) optional

Example: A

The type of the DNS record. For example: A, CNAME, TXT, ...

per_page integer 1 – 200 optional

Example: 2

Number of items returned per page

Default: 20

page integer >= 1 optional

Example: 1

Which 'page' of paginated results to return.

Default: 1

Request: `/v2/domains/{domain_name}/records`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/domains/example.com/records"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    opt := &godo.ListOptions{
      Page:    1,
      PerPage: 200,
    }

domains, _, err := client.Domains.List(ctx, opt)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

records = client.domain_records.all(for_domain: 'example.com')
records.each

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.domains.list_records(domain_name="example.com")

Responses

200

The response will be a JSON object with a key called domain_records. The value of this will be an array of domain record objects, each of which contains the standard domain record attributes. For attributes that are not used by a specific record type, a value of null will be returned. For instance, all records other than SRV will have null for the weight and port attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

domain_records array of object optional

Show child properties

data string optional

Example: ns1.digitalocean.com

Variable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

links object optional

Show child properties

pages anyOf optional

One of:

Forward Links

last string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links

first string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "domain_records": [
    {
      "data": "ns1.digitalocean.com",
      "flags": null,
      "id": 28448429,
      "name": "@",
      "port": null,
      "priority": null,
      "tag": null,
      "ttl": 1800,
      "type": "NS",
      "weight": null
    },
    {
      "data": "ns2.digitalocean.com",
      "flags": null,
      "id": 28448430,
      "name": "@",
      "port": null,
      "priority": null,
      "tag": null,
      "ttl": 1800,
      "type": "NS",
      "weight": null
    },
    {
      "data": "ns3.digitalocean.com",
      "flags": null,
      "id": 28448431,
      "name": "@",
      "port": null,
      "priority": null,
      "tag": null,
      "ttl": 1800,
      "type": "NS",
      "weight": null
    },
    {
      "data": "1.2.3.4",
      "flags": null,
      "id": 28448432,
      "name": "@",
      "port": null,
      "priority": null,
      "tag": null,
      "ttl": 1800,
      "type": "A",
      "weight": null
    }
  ],
  "links": {},
  "meta": {
    "total": 4
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New Domain Record

/v2/domains/{domain_name}/records

Authorizations: bearer_auth (1 scope) bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Http: Bearer

Required scopes: domain:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new record to a domain, send a POST request to /v2/domains/$DOMAIN_NAME/records.

The request must include all of the required fields for the domain record type being added.

See the attribute table for details regarding record types and their respective required attributes.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

Request Body: `application/json`

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

AAAA

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

CAA

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

CNAME

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

SOA

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

SRV

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

TXT

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

Request: `/v2/domains/{domain_name}/records`

Payload

Content type application/json

{
  "data": "162.10.66.0",
  "flags": null,
  "name": "www",
  "port": null,
  "priority": null,
  "tag": null,
  "ttl": 1800,
  "type": "A",
  "weight": null
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"type":"A","name":"www","data":"162.10.66.0","priority":null,"port":null,"ttl":1800,"weight":null,"flags":null,"tag":null}' \
  "https://api.digitalocean.com/v2/domains/example.com/records"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.DomainRecordEditRequest{
      Type: "A",
      Name: "www",
      Data: "1.2.3.4",
    }

    domainRecord, _, err := client.Domains.CreateRecord(ctx, "example.com", createRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

record = DropletKit::DomainRecord.new(
  type: 'A',
  name: 'www',
  data: '162.10.66.0'
)
client.domain_records.create(record, for_domain: 'example.com')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "type": "A",
  "name": "www",
  "data": "162.10.66.0",
  "priority": None,
  "port": None,
  "ttl": 1800,
  "weight": None,
  "flags": None,
  "tag": None
}

resp = client.domains.create_record(domain_name="example.com", body=req)

Responses

201

The response body will be a JSON object with a key called domain_record. The value of this will be an object representing the new record. Attributes that are not applicable for the record type will be set to null. An id attribute is generated for each record as part of the object.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

domain_record object optional

Show child properties

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

201

{
  "domain_record": {
    "data": "162.10.66.0",
    "flags": null,
    "id": 28448433,
    "name": "www",
    "port": null,
    "priority": null,
    "tag": null,
    "ttl": 1800,
    "type": "A",
    "weight": null
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Domain Record

/v2/domains/{domain_name}/records/{domain_record_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve a specific domain record, send a GET request to /v2/domains/$DOMAIN_NAME/records/$RECORD_ID.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

domain_record_id integer required

Example: 3352896

The unique identifier of the domain record.

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    record, _, err := client.Domains.Record(ctx, "example.com", 3352896)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.domain_records.find(for_domain: 'example.com', id: 3352896)

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

get_resp = client.domains.get_record(domain_name="example.com", domain_record_id=3352896)

Responses

200

The response will be a JSON object with a key called domain_record. The value of this will be a domain record object which contains the standard domain record attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

domain_record object optional

Show child properties

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "domain_record": {
    "data": "162.10.66.0",
    "flags": null,
    "id": 3352896,
    "name": "blog",
    "port": null,
    "priority": null,
    "tag": null,
    "ttl": 1800,
    "type": "A",
    "weight": null
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Domain Record

/v2/domains/{domain_name}/records/{domain_record_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an existing record, send a PUT request to /v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID. Any attribute valid for the record type can be set to a new value for the record.

See the attribute table for details regarding record types and their respective attributes.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

domain_record_id integer required

Example: 3352896

The unique identifier of the domain record.

Request Body: `application/json`

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

Payload

Content type application/json

{
  "name": "blog",
  "type": "CNAME"
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"blog"}' \
  "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    editRequest := &godo.DomainRecordEditRequest{
      Type: "A",
      Name: "blog",
    }

    domainRecord, _, err := client.Domains.EditRecord(ctx, "example.com", 3352896, editRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

record = DropletKit::DomainRecord.new(name: 'blog')
client.domain_records.update(record, for_domain: 'example.com', id: 3352896)

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "blog",
  "type": "CNAME"
}

resp = client.domains.update_record(domain_name="example.com", domain_record_id=2432342, body=req)

Responses

200

The response will be a JSON object with a key called domain_record. The value of this will be a domain record object which contains the standard domain record attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

domain_record object optional

Show child properties

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "domain_record": {
    "data": "162.10.66.0",
    "flags": null,
    "id": 3352896,
    "name": "blog",
    "port": null,
    "priority": null,
    "tag": null,
    "ttl": 1800,
    "type": "A",
    "weight": null
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PATCH Update a Domain Record

/v2/domains/{domain_name}/records/{domain_record_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an existing record, send a PATCH request to /v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID. Any attribute valid for the record type can be set to a new value for the record.

See the attribute table for details regarding record types and their respective attributes.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

domain_record_id integer required

Example: 3352896

The unique identifier of the domain record.

Request Body: `application/json`

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

Payload

Content type application/json

{
  "name": "blog",
  "type": "A"
}

cURL

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"blog","type":"A"}' \
  "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "blog",
  "type": "A"
}

resp = client.domains.patch_record(domain_name="example.com", domain_record_id=2432342, body=req)

Responses

200

The response will be a JSON object with a key called domain_record. The value of this will be a domain record object which contains the standard domain record attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

domain_record object optional

Show child properties

data string optional

Example: ns1.digitalocean.com

flags integer optional Nullable

An unsigned integer between 0-255 used for CAA records.

id integer optional read-only

Example: 28448429

A unique identifier for each domain record.

name string optional

Example: @

The host name, alias, or service being defined by the record.

port integer optional Nullable

The port for SRV records.

priority integer optional Nullable

The priority for SRV and MX records.

tag string optional Nullable

The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

ttl integer optional

Example: 1800

This value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.

type string required

Example: NS

The type of the DNS record. For example: A, CNAME, TXT, ...

weight integer optional Nullable

The weight for SRV records.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "domain_record": {
    "data": "162.10.66.0",
    "flags": null,
    "id": 3352896,
    "name": "blog",
    "port": null,
    "priority": null,
    "tag": null,
    "ttl": 1800,
    "type": "A",
    "weight": null
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Domain Record

/v2/domains/{domain_name}/records/{domain_record_id}

Authorizations: bearer_auth (1 scope) bearer_auth (1 scope)

Http: Bearer

Required scopes: domain:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Http: Bearer

Required scopes: domain:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a record for a domain, send a DELETE request to /v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID.

The record will be deleted and the response status will be a 204. This indicates a successful request with no body returned.

Path Parameters

domain_name string required

Example: example.com

The name of the domain itself.

domain_record_id integer required

Example: 3352896

The unique identifier of the domain record.

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Domains.DeleteRecord(ctx, "example.com", 3352896)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.domain_records.delete(for_domain: 'example.com', id: 3352896)

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "example.com"
}

resp = client.domains.delete_record(domain_name="example.com", domain_record_id=3352896)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

Domain Records

Endpoints

GET List All Domain Records

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Query Parameters

Request: /v2/domains/{domain_name}/records

Responses

Response

POST Create a New Domain Record

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/domains/{domain_name}/records

Responses

Response

GET Retrieve an Existing Domain Record

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/domains/{domain_name}/records/{domain_record_id}

Responses

Response

PUT Update a Domain Record

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/domains/{domain_name}/records/{domain_record_id}

Responses

Response

PATCH Update a Domain Record

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/domains/{domain_name}/records/{domain_record_id}

Responses

Response

DELETE Delete a Domain Record

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/domains/{domain_name}/records/{domain_record_id}

Responses

Response

We can't find any results for your search.

Request: `/v2/domains/{domain_name}/records`

Request Body: `application/json`

Request: `/v2/domains/{domain_name}/records`

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

Request Body: `application/json`

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

Request Body: `application/json`

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`

Request: `/v2/domains/{domain_name}/records/{domain_record_id}`