Domain resources are domain names that you have purchased from a domain name registrar that you are managing through the [DigitalOcean DNS interface](https://docs.digitalocean.com/products/networking/dns/). This resource establishes top-level control over each domain. Actions that affect individual domain records should be taken on the [Domain Records](#tag/Domain-Records) resource.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/digital-ocean-domains-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: DigitalOcean Domains API
version: '2.0'
description: '# Introduction
The DigitalOcean API allows you to manage Droplets and resources within the
DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
name: DigitalOcean API Team
email: api-engineering@digitalocean.com
termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/
servers:
- url: https://api.digitalocean.com
description: production
security:
- bearer_auth: []
tags:
- name: Domains
description: 'Domain resources are domain names that you have purchased from a domain
name registrar that you are managing through the
DigitalOcean DNS interface.
This resource establishes top-level control over each domain. Actions that
affect individual domain records should be taken on the
Domain Records resource.'
paths:
/v2/domains:
get:
operationId: domains_list
summary: List All Domains
description: To retrieve a list of all of the domains in your account, send a GET request to `/v2/domains`.
tags:
- Domains
parameters:
- $ref: '#/components/parameters/per_page'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/all_domains_response'
'401':
$ref: '#/components/responses/unauthorized'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/domains\""
- lang: Go
source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n opt := &godo.ListOptions{\n Page: 1,\n PerPage: 200,\n }\n\ndomains, _, err := client.Domains.List(ctx, opt)\n}"
- lang: Ruby
source: 'require ''droplet_kit''
token = ENV[''DIGITALOCEAN_TOKEN'']
client = DropletKit::Client.new(access_token: token)
domains = client.domains.all
domains.each'
- lang: Python
source: 'import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.domains.list()'
security:
- bearer_auth:
- domain:read
post:
operationId: domains_create
summary: Create a New Domain
description: 'To create a new domain, send a POST request to `/v2/domains`. Set the "name"
attribute to the domain name you are adding. Optionally, you may set the
"ip_address" attribute, and an A record will be automatically created pointing
to the apex domain.'
tags:
- Domains
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/domain'
example:
name: example.com
responses:
'201':
$ref: '#/components/responses/create_domain_response'
'401':
$ref: '#/components/responses/unauthorized'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"name\":\"example.com\",\"ip_address\":\"1.2.3.4\"}' \\\n \"https://api.digitalocean.com/v2/domains\""
- lang: Go
source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n )\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n createRequest := &godo.DomainCreateRequest{\n Name: \"example.com\",\n IPAddress: \"1.2.3.4\",\n }\n\n domain, _, err := client.Domains.Create(ctx, createRequest)\n\n}"
- lang: Ruby
source: "require 'droplet_kit'\ntoken = ENV['DIGITALOCEAN_TOKEN']\nclient = DropletKit::Client.new(access_token: token)\n\ndomain = DropletKit::Domain.new(\n name: 'example.com',\n ip_address: '1.2.3.4'\n)\nclient.domains.create(domain)"
- lang: Python
source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"example.com\"\n}\n\nresp = client.domains.create(body=req)"
security:
- bearer_auth:
- domain:create
/v2/domains/{domain_name}:
get:
operationId: domains_get
summary: Retrieve an Existing Domain
description: To get details about a specific domain, send a GET request to `/v2/domains/$DOMAIN_NAME`.
tags:
- Domains
parameters:
- $ref: '#/components/parameters/domain_name'
responses:
'200':
$ref: '#/components/responses/existing_domain'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/domains/example.com\""
- lang: Go
source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n domain, _, err := client.Domains.Get(ctx, \"example.com\")\n}"
- lang: Ruby
source: 'require ''droplet_kit''
token = ENV[''DIGITALOCEAN_TOKEN'']
client = DropletKit::Client.new(access_token: token)
client.domains.find(name: ''example.com'')'
- lang: Python
source: 'import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.domains.get(domain_name="example.com")'
security:
- bearer_auth:
- domain:read
delete:
operationId: domains_delete
summary: Delete a Domain
description: To delete a domain, send a DELETE request to `/v2/domains/$DOMAIN_NAME`.
tags:
- Domains
parameters:
- $ref: '#/components/parameters/domain_name'
responses:
'204':
$ref: '#/components/responses/no_content'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X DELETE \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/domains/example.com\""
- lang: Go
source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n _, err := client.Domains.Delete(ctx, \"example.com\")\n}"
- lang: Ruby
source: 'require ''droplet_kit''
token = ENV[''DIGITALOCEAN_TOKEN'']
client = DropletKit::Client.new(access_token: token)
client.domains.delete(name: ''example.com'')'
- lang: Python
source: 'import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
delete_resp = client.domains.delete(domain_name="example.com")'
security:
- bearer_auth:
- domain:delete
components:
schemas:
meta_properties:
type: object
description: Information about the response itself.
properties:
total:
description: Number of objects returned by the request.
type: integer
example: 1
link_to_last_page:
type: object
properties:
last:
description: URI of the last page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=2
error:
type: object
properties:
id:
description: 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."
type: string
example: not_found
message:
description: A message providing additional information about the error, including details to help resolve it when possible.
type: string
example: The resource you were accessing could not be found.
request_id:
description: Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
type: string
example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9
required:
- id
- message
backward_links:
allOf:
- $ref: '#/components/schemas/link_to_first_page'
- $ref: '#/components/schemas/link_to_prev_page'
meta:
type: object
properties:
meta:
allOf:
- $ref: '#/components/schemas/meta_properties'
- required:
- total
required:
- meta
link_to_next_page:
type: object
properties:
next:
description: URI of the next page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=2
pagination:
type: object
properties:
links:
$ref: '#/components/schemas/page_links'
link_to_prev_page:
type: object
properties:
prev:
description: URI of the previous page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=1
domain:
type: object
properties:
name:
type: string
description: The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, `example.com` is a valid domain name.
example: example.com
ip_address:
type: string
writeOnly: true
description: This optional attribute may contain an IP address. When provided, an A record will be automatically created pointing to the apex domain.
example: 192.0.2.1
ttl:
type:
- integer
- 'null'
readOnly: true
description: This value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
example: 1800
zone_file:
type:
- string
- 'null'
readOnly: true
description: This attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.
example: '$ORIGIN example.com.
$TTL 1800
example.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. 1415982609 10800 3600 604800 1800
example.com. 1800 IN NS ns1.digitalocean.com.
example.com. 1800 IN NS ns2.digitalocean.com.
example.com. 1800 IN NS ns3.digitalocean.com.
example.com. 1800 IN A 1.2.3.4
'
link_to_first_page:
type: object
properties:
first:
description: URI of the first page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=1
forward_links:
allOf:
- $ref: '#/components/schemas/link_to_last_page'
- $ref: '#/components/schemas/link_to_next_page'
page_links:
type: object
properties:
pages:
anyOf:
- $ref: '#/components/schemas/forward_links'
- $ref: '#/components/schemas/backward_links'
- {}
example:
pages:
first: https://api.digitalocean.com/v2/account/keys?page=1
prev: https://api.digitalocean.com/v2/account/keys?page=2
responses:
create_domain_response:
description: The response will be a JSON object with a key called `domain`. The value of this will be an object that contains the standard attributes associated with a domain.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
properties:
domain:
$ref: '#/components/schemas/domain'
example:
domain:
name: example.com
ttl: 1800
zone_file: null
unexpected_error:
description: Unexpected error
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: example_error
message: some error message
no_content:
description: The action was successful and the response body is empty.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
not_found:
description: The resource was not found.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: not_found
message: The resource you requested could not be found.
too_many_requests:
description: API Rate limit exceeded
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: too_many_requests
message: API Rate limit exceeded.
all_domains_response:
description: The response will be a JSON object with a key called `domains`. The value of this will be an array of Domain objects, each of which contain the standard domain attributes.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
allOf:
- type: object
properties:
domains:
type: array
items:
$ref: '#/components/schemas/domain'
description: Array of volumes.
required:
- domains
- $ref: '#/components/schemas/pagination'
- $ref: '#/components/schemas/meta'
example:
domains:
- name: example.com
ttl: 1800
zone_file: '$ORIGIN example.com.
$TTL 1800
example.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. 1415982609 10800 3600 604800 1800
example.com. 1800 IN NS ns1.digitalocean.com.
example.com. 1800 IN NS ns2.digitalocean.com.
example.com. 1800 IN NS ns3.digitalocean.com.
example.com. 1800 IN A 1.2.3.4
'
links: {}
meta:
total: 1
existing_domain:
description: The response will be a JSON object with a key called `domain`. The value of this will be an object that contains the standard attributes defined for a domain.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
properties:
domain:
$ref: '#/components/schemas/domain'
example:
domain:
name: example.com
ttl: 1800
zone_file: '$ORIGIN example.com.
$TTL 1800
example.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. 1415982611 10800 3600 604800 1800
example.com. 1800 IN NS ns1.digitalocean.com.
example.com. 1800 IN NS ns2.digitalocean.com.
example.com. 1800 IN NS ns3.digitalocean.com.
example.com. 1800 IN A 1.2.3.4
'
unauthorized:
description: Unauthorized
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: unauthorized
message: Unable to authenticate you.
server_error:
description: Server error.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: server_error
message: Unexpected server-side error
parameters:
domain_name:
name: domain_name
description: The name of the domain itself.
in: path
schema:
type: string
example: example.com
required: true
per_page:
in: query
name: per_page
required: false
description: Number of items returned per page
schema:
type: integer
minimum: 1
default: 20
maximum: 200
example: 2
page:
in: query
name: page
required: false
description: Which 'page' of paginated results to return.
schema:
type: integer
minimum: 1
default: 1
example: 1
headers:
ratelimit-reset:
schema:
type: integer
example: 1444931833
description: The time when the oldest request will expire. The value is given in Unix epoch time. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
ratelimit-remaining:
schema:
type: integer
example: 4816
description: The number of requests in your hourly quota that remain before you hit your request limit. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
ratelimit-limit:
schema:
type: integer
example: 5000
description: 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.
securitySchemes:
bearer_auth:
type: http
scheme: bearer
description: '## 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](https://cloud.digitalocean.com/account/api/tokens)
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](https://docs.digitalocean.com/reference/api/oauth-api/)
- `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"
```
'