Docs API Basics

API Basics

API keys

An API key is required for all API access. API keys may be generated at Preferences -> API keys.

The API key should be provided for every request as part of the Authorization header:

Authorization: Bearer key_SonrxAvoBCaFFFKedB5WDmUE6nCnYaXS

API endpoint

The DNScaster API is https only. TLS 1.2+ is required.

The endpoint always starts with https://api.dnscaster.com/v1/.

Request headers

Accept

The API only sends JSON responses. All API requests must indicate that they are requesting JSON payloads:

Accept: application/json
Authentication

Authentication uses a standard HTTP Authorization header:

Authorization: Bearer key_SonrxAvoBCaFFFKedB5WDmUE6nCnYaXS

Only Bearer tokens are supported. Basic and Digest auth are not supported.

API keys may be be created and managed in the management portal under Preferences -> API keys.

Content type

Payloads sent to the API via POST or PUT requests may be sent as JSON or as standard url-encoded form data. JSON payloads are recommended as they are much easier to read/debug when using nested data.

Content-type: application/json
Content-type: application/x-www-form-urlencoded
User agent

If you’re writing a DNScaster library for use by 3rd-parties, a User-agent header with contact info for the library author(s) is required (a GitHub or other URL is fine). This enables us to reach out in the event we see something that needs to be addressed.

For everyone else, the User-agent header is optional, but adding one and including some kind of version identifier may be useful for your own debugging.

This field is logged without encryption or sanitization. Please keep this in mind before sending personally identifying information.

User-agent: <Your library or app, with URL or role email>

Response headers

Content type

Responses from the API will indicate the delivery of a JSON payload:

Content-type: application/json
Request ID

All API responses will include X-Request-ID, which is unique to each request. If you have a question about a specific API call, sending the request ID will make it much easier for us to help you debug the issue.

X-Request-ID: rq_0w5HV6ziYCKlHGam5BkdHE
Status

API responses all deliver an appropriate HTTP Status: header. The numeric portion of this status code should be checked before attempting to parse the body response. See Status codes for more details.

Paging of responses

Many of the “List” API calls return paged responses. They take a common set of query parameters:

  • after - The last resource ID seen. The new page of results will start at the next ID.
  • direction - Sort as asc (default) or desc.
  • max_results - Number of results per page. Defaults to 100, with a typical maximum of 1000.
  • sort - Sort results using this field. Default is id unless indicated otherwise.

DNScaster’s resource IDs are sortable. Note that they are case-sensitive and use an ASCII sort.

Paged responses are returned in a collection:

{
  "collection": [
    { ... },
    { ... }
  ],
  "more_results": false
}

The more_results field indicates whether there are additional results. If true, repeat the query with the same parameters plus after=LAST-ID where LAST-ID is the id of the last returned result.