Overview

This page provides an overview of the official DNSimple API v2.

The complete definition of our API is available in OpenAPIv3 YAML and JSON formats.

• URL
• Testing
• Current Version
• Content Types
• Authentication
• Authorization
• Response Codes
• Responses
• Errors
• Timestamps
• Account scope
• Pagination
• Filtering
• Sorting
• Rate limiting
• More Examples

URL

All API access is over HTTPS, and accessed from the api.dnsimple.com domain.

In order to maintain compatibility in the future, all requests must specify an API version, which is appended to the URL.

https://api.dnsimple.com/v2/

Testing

We maintain a separate environment for testing called Sandbox accounts. Sandbox API calls must use the api.sandbox.dnsimple.com domain.

Current Version

The current API version is v2.

Content Types

Unless otherwise specified in specific API method documentations, API v2 only supports the JSON content type. HTTP requests must be JSON-encoded, and HTTP responses will contain JSON-encoded payloads.

The content type header must be explicitly specified in any HTTP request:

curl -u 'EMAIL:PASSWORD' -H 'Content-Type: application/json' https://api.dnsimple.com/v2/whoami

To improve readability, the header may be omitted in some examples in this documentation.

Authentication

There two ways to authenticate through DNSimple API: the HTTP Basic Authentication and the OAuth2 token.

When you create an OAuth2 token programmatically, the token is scoped to the specific account granted during the OAuth2 dance. When you create an OAuth2 token from the application, you can create either a user token or an account token.

The HTTP Basic Authentication always authenticate you as a user.

HTTP Basic Authentication

curl -u 'EMAIL:PASSWORD' https://api.dnsimple.com/v2/whoami

Users with two-factor authentication enabled must send an extra HTTP header for the request.

curl -u 'EMAIL:PASSWORD' -H "X-Dnsimple-OTP: 2FA-TOKEN" https://api.dnsimple.com/v2/whoami

In case two-factor authentication is enabled but the header is not sent, the application will respond with a 401 and a response header: X-Dnsimple-OTP: required.

OAuth2 Token

curl -H 'Authorization: Bearer OAUTH-TOKEN' https://api.dnsimple.com/v2/whoami

Note that Oauth2 tokens can be acquired programmatically and via OAuth dance or can be generated from the user/account sections in the DNSimple application.

Account tokens vs User tokens

API v2 offers 2 types of tokens: account tokens and user tokens.

The user token gives you access to any resource associated to any account the user has access to. If you have been granted specific domain permissions using Domain Access Control, your access will be limited by your given role.

Conversely, an account token gives you access only to the resources connected to that account.

We recommend to use account tokens, unless your application needs multi-account access via single token.

Authorization

Scoped account access tokens, which allow granular permissions to specific resources (e.g. domains, certificates or zones) are available for certain plans. When calling an API endpoint with a scoped access token, an authorization check will be performed to verify whether the access token is authorized to access the specified resource(s).

Response Codes

DNSimple uses conventional HTTP response codes to indicate success or failure of an API request.

Successful

• 200 OK - Everything worked as expected.
• 201 Created - The request was successful and a resource was created. This is typically a response from a POST request to create a resource, such as the registration of a Domain or the creation of a Contact.
• 202 Accepted - The request has been accepted for processing. This is typically a response from a POST request that is handled async in our system, such as a Domain transfer request.
• 204 No Content - The request was successful but the response body is empty. This is typically a response from a DELETE request to delete a resource.

Error

• 400 Bad Request - The request is invalid or there is an issue with the request payload. See Errors.
• 401 Unauthorized - The authentication credentials are invalid. See Authentication.
• 402 Payment Required - Your account is not subscribed or not in good standing.
• 403 Permission Denied - The authenticated account doesn’t have permissions to access the resource. See Authorization.
• 404 Not Found - The requested resource doesn’t exist or the authenticated account doesn’t have permissions to access the resource.
• 429 Too Many Requests - You exceeded the allowed number of requests per hour and your request has temporarily been throttled. See Rate limitting.

Kaboom!

• 500, 502, 503, 504 Server errors - something went wrong on DNSimple’s end.

Responses

All successful responses will be returned as a JSON object with at least one key: data.

The data element will contain either a single JSON object or a list of JSON objects, depending on the endpoint.

{
  "data": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith"
  }
}

Errors

All responses with an 4xx and 5xx response code will have a JSON object as body, with at least a message key.

Here are some examples of response bodies for response codes:

400 - Bad Request

Depending on the error, the response may include an errors key with more details about why the request was unsuccessful and what specific data is invalid.

{ "message": "TLD .PINEAPPLE is not supported" }

{
  "message": "The contact cannot be deleted: contact is in use",
  "errors": {}
}

{
  "message": "We were unable to authorize the payment for this purchase on your card. Payment gateway returned error code: card_declined (generic_decline).",
  "errors": {}
}

{
  "message": "Validation failed",
  "errors": {
    "ttl": ["is not a number"],
    "content": ["can't be blank"],
    "record_type": ["unsupported"]
  }
}

{
  "message": "Validation failed",
  "errors": {
    "address1": ["can't be blank"],
    "city": ["can't be blank"],
    "country": ["is the wrong length (should be 2 characters)","is not a valid country"],
    "email": ["can't be blank","is an invalid email address"],
    "first_name": ["can't be blank"],
    "last_name": ["can't be blank"],
    "postal_code": ["can't be blank"],
    "state_province": ["can't be blank"],
    "phone": ["is probably not a phone number"]
  }
}

401 - Unauthorized

{"message": "Authentication failed"}

402 - Payment required

{"message": "This action cannot be completed because you have purchase invoices that need to be paid for: 12345-1010. Please retry the payment following these instructions https://support.dnsimple.com/articles/account-invoice-history/#retrying."}

403 - Permission Denied

{"message": "Permission Denied. Required Scope: domains:*:read"}

{"message": "Permission Denied. Required Scope: registrar:{domain_name}:write"}

404 - Not found

{"message": "Not Found"}

412 - Precondition Failed

{"message": "Let's Encrypt feature is not enabled for the account email@example.com"}

{"message": "The certificate requires the custom-name feature that is not available on the current plan for the account email@example.com"}

{"message": "The certificate requires the SAN feature that is not available on the current plan for the account email@example.com"}

{"message": "The certificate requires the wildcard feature that is not available on the current plan for the account email@example.com"}

428 - Precondition Required

{"message": "Certificate not issued"}

{"message": "Private key not present"}

429 - Too Many Requests

{"message": "quota exceeded"}

504 - Gateway Timeout

{"message": "Could not query zone, connection timed out"}

Timestamps

All the timestamps and the dates are formatted according the ISO-8601 standard.

2016-12-11T17:31:51Z # Timestamp
2016-12-11           # Date

Account scope

The majority of API methods are designed to be executed within the scope of a specific account. In this documentation, the account parameter is identified by the :account string in the API method path:

# An example of the API method to list the domains
# for a specific account
GET /:account/domains

The account identifier must be supplied regardless the authentication mechanism, even if you use an account token. Remember that an account token limits the permission to a specific account, whereas an user token allows to access any resource on any account associated with the user.

The account identifier is represented by a numerical account ID. You can obtain the account identifier either programmatically or manually.

Getting the ID manually from the URL

URLs in the main DNSimple application are also account scoped, the account ID can be reused in the API calls. To get the account ID, log into DNSimple, click on the account switch on the top-right of any DNSimple page, select the relevant account. Once selected, you will be sent to a page that contains an ID in the URL, for example:

https://dnsimple.com/a/1234/domains

The digit after the /a in the path is the ID of the account. In this specific example, the account identifier is 1234.

Getting the ID programmatically with an Account access token

If you use an account token and you want to get the ID programmatically, the simplest way is to perform a whoami API call. The response will contain the account identifier as part of the account payload.

{
  "data": {
    "user": null,
    "account": {
      "id": 1,
      "email": "example-account@example.com",
      "plan_identifier": "dnsimple-professional",
      "created_at": "2015-09-18T23:04:37Z",
      "updated_at": "2016-06-09T20:03:39Z"
    }
  }
}

Getting the ID programmatically with a User access token

If you use an user token and you want to get the ID programmatically, you need to fetch the list of all the accounts associated with the user executing a listAccounts API call.

{
  "data": [
    {
      "id": 123,
      "email": "john@example.com",
      "plan_identifier": "dnsimple-personal",
      "created_at": "2011-09-11T17:15:58Z",
      "updated_at": "2016-06-03T15:02:26Z"
    },
    {
      "id": 456,
      "email": "ops@company.com",
      "plan_identifier": "dnsimple-professional",
      "created_at": "2012-03-16T16:02:54Z",
      "updated_at": "2016-06-14T11:23:16Z"
    }
  ]
}

The response contains one or more accounts. Select the relevant account based on a known criteria (e.g. the name or an user input), and get the corresponding ID.

Pagination

Any API endpoint that returns a list of items requires pagination. By default we will return 30 records from any listing endpoint.

If an API endpoint returns a list of items, then it will include a pagination object that contains pagination information.

The pagination object contains the following details:

• current_page: The page currently returned (default: 1)
• per_page: The number of entries returned per page (default: 30)
• total_entries: The total number of entries available in the entire collection
• total_pages: The total number of pages available given the current per_page value

For example:

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith"
    },
    {
      "id": 3,
      "first_name": "John",
      "last_name": "Smith",
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

You may include the following arguments as query parameters when you call an API endpoint that supports pagination:

• page: The page to return (default: 1)
• per_page: The number of entries to return per page (default: 30, maximum: 100)

For example:

https://api.dnsimple.com/v2/1010/domains?per_page=100&page=2

Filtering

Filtering makes it possible to ask only for the exact subset of data that you you’re looking for.

With potential hundreds of result entries, it’s covenient to apply a filter and receive only the interesting data.

API v2 supports this feature via query string.

Example

List all domains in the account 1010 that have name matching "example":

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/domains?name_like=example

Please have a look at the documentation of each endpoint to know about the filters it supports.

Sorting

API v2 results are implicitly sorted according to policies that vary from endpoint to endpoint.

You can decide your own sorting policy for each single API call via the sort parameter.

This parameter accepts a set of comma separated key-value pairs: the name of a field and the order criteria (asc for ascending and desc for descending).

The order of fields is relevant, as it will determine the priority of the sorting policies.

Example

List all domains in the account 1010 sorting them by expiration date (asc) and id (desc)

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/domains?sort=expiration:asc,id:desc

Rate limiting

There is a limit to the number of requests that you can perform per hour.

• For authenticated requests, you can make up to 2400 requests per hour.
• For unauthenticated requests, you can make up to 30 requests per hour.

You can see your current rate limit status by checking the HTTP headers of any API request:

$ curl -H "Authorization: Bearer ACCESS-TOKEN" -I "https://api.dnsimple.com/v2/whoami"

HTTP/1.1 200 OK
Date: Fri, 11 Dec 2015 11:15:42 GMT
Status: 200 OK
Connection: close
X-RateLimit-Limit: 2400
X-RateLimit-Remaining: 2399
X-RateLimit-Reset: 1449836141

The headers have all the information you need to know about your current rate limit status:

Once you go over the rate limit, you will receive an error response:

$ curl -H "Authorization: Bearer ACCESS-TOKEN" -I "https://api.dnsimple.com/v2/whoami"

HTTP/1.1 429 Too Many Requests
X-Ratelimit-Limit: 2400
X-Ratelimit-Remaining: 0
X-RateLimit-Reset: 1449836141
Content-Type: application/json; charset=utf-8
Content-Length: 28

{"message":"quota exceeded"}

More Examples

You can learn more about interacting with the API through the DNSimple API Examples repository on GitHub. This repository holds examples in various programming languages that can help guide you through using the API.

Additionally, you can find various example web applications in the DNSimple organization on GitHub that will guide you through the creation of a basic web application that connects to the DNSimple API, obtains an OAuth token, and lists domains.