Back to top

MyDNSHost API

This document describes the current API (Version 1.0) for MyDNSHost.

User Authentication

Authentication is done using HTTP Basic Auth. Unless otherwise documented, all end-points require authentication.

Authentication via Basic Auth gives you full access to the account (Same as an API Key with all permissions set to true).

If a 2FA Key is required for the account, this must be passed as a HTTP Header:

X-2FA-Key: 123456

Devices can be saved as Trusted Devices to allow them to bypass the need to enter the 2FA key every time.

This can be done by passing a X-2FA-SAVE-DEVICE header when logging in with a valid 2FA Key:

X-2FA-SAVE-DEVICE: Some Device Name

The API Response will then include a device_id item that can be stored and used for future logins in place of the 2FA Key:

X-2FA-DEVICE-ID: 84FDBE2B-0FB2-461C-9E7B-31A2AF5E52F6

If a X-2FA-DEVICE-ID is passed alongside the X-2FA-SAVE-DEVICE header then that device ID will be used to rememebr the device, otherwise the API will generate a new one for you.

API Key Authentication

If you have a valid API Key, this can be used instead of Basic Auth and offers greater control over what end points can be accessed.

API Keys can be limited as to what they can see/do.

  • domains_read: Has access to GET on /domains end-points

  • domains_write: Has access to POST or DELETE on /domains end-points

  • user_read: Has access to GET on /users end-points

  • user_write: Has access to POST or DELETE on /users end-points

You can log in using an API Key by adding the following headers:

X-API-User: SomeUser@example.org
X-API-Key: ede99f46-198a-411a-b066-5f1c92a6d26d

You can also use a domain-key, which behaves like an API key that has no user_read or user_write permissions, and can only interact with a single domain. Domain keys are linked to domains not users.

X-Domain: example.org
X-Domain-Key: 9426F536-2559-4FA0-BA50-644C90B5FAE4

Session Authentication

You can obtain a session token from the /session end point, and then use it for future requests by passing the X-SESSION-ID header instead of any other authentication headers.

X-SESSION-ID: 9pbobqkbiqvhll2ngia8bg0ijd

Session tokens will expire approximately 15 minutes after they were last used.

Request-ID

For any of the requests, you can pass a X-Request-ID header:

X-Request-ID: SomeUniqueID

Which will be returned in the body of any reponse as a reqid field.

Rate Limiting

Requests to the API may be subject to rate limiting. The API uses standard rate-limiting headers to denote the rate limit information, for examples:

X-RateLimit-Limit: 1024
X-RateLimit-Remaining: 512
X-RateLimit-Reset: 1508738400

These will show your total request limit amount for this window, how many requests you have remaining in the window, and the time that the limit resets.

If you have exceeded your limit you will recieve a HTTP Error 429 message instead of the usual API response.

Different keys/users may have different limits. If you need a greater limit, please get in touch.

General

General API Endpoints.

API Ping

Ping the API
GET/ping/{time}

This tests that the API is up and running. The API will respond with a non-error and include the time if provided, this does not require authentication.

Example URI

GET https://api.mydnshost.co.uk/1.0/ping/123456
URI Parameters
HideShow
time
number (optional) Example: 123456

The current time, will be echoed back.

Response  200
HideShow

If the time is not provided, then the response field is ommited entirely.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcb5e953b5d",
  "method": "ping/123456",
  "response": {
    "time": "123456"
  }
}

Get the current user information

Get User information
GET/userdata

This lets you see what user you are authenticated as and your current access level based on your authentication.

Example URI

GET https://api.mydnshost.co.uk/1.0/userdata
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcb98d67ba3",
  "method": "userdata",
  "response": {
    "user": {
      "id": "2",
      "email": "user@example.org",
      "realname": "Some User"
    },
    "access": {
      "domains_read": true,
      "domains_write": false,
      "user_read": false,
      "user_write": false
    }
  }
}

Get the current api version

Get version information
GET/version

This is used to see what version of the API you are accessing, this does not require authentication.

Example URI

GET https://api.mydnshost.co.uk/1.0/version
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcb9e378fd6",
  "method": "version",
  "response": {
    "version": "1.0"
  }
}

Session tokens

Open a new session and get a session token
GET/session

This will obtain a new session token for use in future requests.

Example URI

GET https://api.mydnshost.co.uk/1.0/session
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58c33b3ec880c",
  "method": "session",
  "response": {
    "session": "rgmc55ghpbhjmv1qg7ub6q3879"
  }
}

Close the current session
DELETE/session

This will close the current session to prevent any future requests.

Example URI

DELETE https://api.mydnshost.co.uk/1.0/session
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58c33b714169b",
  "method": "session",
  "response": {
    "session": ""
  }
}

Forgot Password

Initiate a Forgot Password request
POST/forgotpassword

This will cause an email to be sent to the user with a link to click on to reset their password.

Example URI

POST https://api.mydnshost.co.uk/1.0/forgotpassword
Request  Request password reset
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "email": "admin@example.org"
  }
}
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
  "respid": "5934bda4bb50c",
  "method": "forgotpassword",
  "response": {
    "success": "Password reset was submitted, please check your email for further instructions."
  }
}

Forgot Password Confirm

Confirm a Forgot Password request
POST/forgotpassword/confirm/{userid}

This will confirm a forgot-password request for the given user, a successful confirmation will send the user an email to confirm the password was chagned.

Example URI

POST https://api.mydnshost.co.uk/1.0/forgotpassword/confirm/1
URI Parameters
HideShow
userid
string (required) Example: 1

The user ID.

Request  Confirm password reset
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "BcEBEQAxCAMwSQPaKyCH8fNv4RNnS1EiD7rNfIiMHuHmfZvPv8VWTdgJ0egBzx8",
    "password": "n3w_p@55w0rd"
  }
}
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
  "respid": "5934be2091a0a",
  "method": "forgotpassword/confirm/1",
  "response": {
    "success": "Password was changed, you can now login."
  }
}
Response  400
HideShow

If there is an error with the request you will get an error reply

Headers
Content-Type: application/json
Body
{
  "respid": "5934be3c48047",
  "method": "forgotpassword/confirm/1",
  "error": "User does not require password reset."
}

Register new account

Initiate a registration request
POST/register

This will cause an email to be sent to the user with a link to click on to confirm their registration.

Example URI

POST https://api.mydnshost.co.uk/1.0/register
Request  Registration
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "email": "user10@example.org",
    "realname": "User Ten"
  }
}
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
  "respid": "5934bea6b4a1c",
  "method": "register",
  "response": {
    "id": "56",
    "email": "user10@example.org",
    "realname": "User Ten"
  }
}

Registration Confirmation

Confirm a Forgot Password request
POST/register/confirm/{userid}

This will confirm a registration request for the given user.

Example URI

POST https://api.mydnshost.co.uk/1.0/register/confirm/56
URI Parameters
HideShow
userid
string (required) Example: 56

The new user ID.

Request  Confirm registration
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "C28E68B6-17A9-4F43-8F03-3CFF519FC3DA",
    "password": "n3w_p@55w0rd"
  }
}
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
  "respid": "5934bf2bc9a5d",
  "method": "register/confirm/56",
  "response": {
    "success": "Registration was successful, you can now log in."
  }
}
Response  400
HideShow

If there is an error with the request you will get an error reply

Headers
Content-Type: application/json
Body
{
  "respid": "5934bf4001861",
  "method": "register/confirm/56",
  "error": "User does not require verification."
}

Users

Endpoints for dealing with user accounts

User list

Get the list of known users
GET/users

For a user with the manage_users permission, this will return all the known users. Users without this permission will just see themselves.

Example URI

GET https://api.mydnshost.co.uk/1.0/users
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcba77c1505",
    "method": "users",
    "response":[
        {
            "id": "2",
            "email": "user@example.org",
            "realname": "Some User"
        }
    ],
}

Manipulate Users

Get information about a specific user
GET/users/{userid}

Returns complete information about the requested user if the user has permission to see the requested user.

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcba77c1505",
    "method": "users",
    "response": {
        "id": "2",
        "email": "user@example.org",
        "realname": "Some User"
        "disabled": "false",
        "permissions": []
    }
}

Update information about a specific user
POST/users/{userid}

Allows updating user information on a user account that you have permission to modify. Any fields that are passed in will be updated, fields not passed will be unchanged.

If you have manage_permissions you can also pass a map of permissions where the key is the permission, and the value is true or false to grant/revoke the permission. Permissions not given will be left unchanged. The meta-permission of all can be used to set the value of all permissions.

Example URI

POST https://api.mydnshost.co.uk/1.0/users/2
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Request  Change realname and Password
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "realname": "Some Real User",
    "password": "NewPassword"
  }
}
Response  200
HideShow

The response on success will show the user account as it exists after the change.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcbc34234e3",
  "method": "users/2",
  "response": {
    "id": "2",
    "email": "user@example.org",
    "realname": "Some Real Name",
    "updated": true
  }
}
Response  400
HideShow

If there is an error you will get an error key rather than a response key in the output

Headers
Content-Type: application/json
Body
{
  "respid": "58bcbcc7dc8d1",
  "method": "users/2",
  "error": "Error updating user: 2"
}

Delete a specific user
DELETE/users/{userid}

This will allow a user with the manage_users permission to delete the user specified, or allow a user to delete themselves. If self-deleting is enabled and you try to delete the current user, the API will give you a confirm code that you need to use to perform a confirmed delete.

Deleting a user will disassociate them with any domains, but will not remove the domains.

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/2
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcbde798d3a",
    "method": "users/2",
    "response":[
        "deleted": "true"
    ]
}

Confirm delete the current user

This endpoint is used to perform a confirmed delete of a given user.

Deleting a user will disassociate them with any domains, but will not remove the domains.

Confirm delete the current user
DELETE/users/{userid}/confirm/{confirmcode}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/2/confirm/c00696d9
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

confirmcode
string (required) Example: c00696d9

The confirm code provided by the initial delete attempt.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcbde798d3a",
    "method": "users/2/confirm/c00696d9",
    "response":[
        "deleted": "true"
    ]
}

Confirm delete the current user with 2FA

This endpoint is used to perform a confirmed delete of a given user who has 2fa enabled.

Deleting a user will disassociate them with any domains, but will not remove the domains.

Confirm delete the current user with 2FA
DELETE/users/{userid}/confirm/{confirmcode}/{twofactorcode}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/2/confirm/c00696d9/123456
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

confirmcode
string (required) Example: c00696d9

The confirm code provided by the initial delete attempt.

twofactorcode
string (required) Example: 123456

A valid 2FA code for this user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcbde798d3a",
    "method": "users/2/confirm/c00696d9/123456",
    "response":[
        "deleted": "true"
    ]
}

Create a user

Create a user
POST/users/create

This allows a user with the manage_users permission to create new users.

This behaves similarily to update user except that you must pass in the email and realname fields.

You can also either pass in a password field to set the password, or to simulate a user registration you can pass in sendWelcome with a value of true

Example URI

POST https://api.mydnshost.co.uk/1.0/users/create
Request  Change realname and Password
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "email": "newuser@example.org",
    "realname": "Some new User",
    "password": "NewPassword"
  }
}
Response  200
HideShow

The response on success will show the user account as it exists after creation.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcbe6b76cee",
  "method": "users/create",
  "response": {
    "id": "6",
    "email": "newuser@example.org",
    "realname": "Some new User",
    "updated": true
  }
}
Response  400
HideShow

On error, you will get an error rather than a response

Headers
Content-Type: application/json
Body
{
  "respid": "58bcbe8c7ac06",
  "method": "users/create",
  "error": "Error creating user."
}

Resend Welcome Message

Request a welcome email be resent to a user.
POST/users/{userid}/resendwelcome

If a user is still pending verification, we can re-send the welcome email to them. (This requires the manage_users permission)

Example URI

POST https://api.mydnshost.co.uk/1.0/users/1/resendwelcome
URI Parameters
HideShow
userid
string (required) Example: 1

The user ID.

Request  request a welcome email be resent
HideShow

The body of this request is empty

Headers
Content-Type: application/json
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
  "respid": "5934c0a6e5bf3",
  "method": "users/56/resendwelcome",
  "response": {
    "success": "Registration email resent."
  }
}
Response  400
HideShow

If there is an error with the request you will get an error reply

Headers
Content-Type: application/json
Body
{
  "respid": "5934c05e6b420",
  "method": "users/56/resendwelcome",
  "error": "User has already completed registration."
}

Accept terms of service

Accept terms of service.
POST/users/{userid}/acceptterms

If a user has not accepted the terms of service this allows them to do so. (This requires the user_write permission)

Example URI

POST https://api.mydnshost.co.uk/1.0/users/self/acceptterms
URI Parameters
HideShow
userid
string (required) Example: self

The user ID (must be own user account or “self”).

Request  Accept terms of service
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "acceptterms": "true"
  }
}
Response  200
HideShow

The response on success will show a message of success.

Headers
Content-Type: application/json
Body
{
    "respid": "5b1df1e976654",
    "method": "users/self/acceptterms",
    "response":{
        "acceptterms": "Terms accepted."
    },
}
Response  400
HideShow

If there is an error with the request you will get an error reply

Headers
Content-Type: application/json
Body
{
  "respid": "5b1df1e976654",
  "method": "users/self/resendwelcome",
  "error": "There was an error accepting the terms of service."
}

API Keys

Get known API Keys
GET/users/{userid}/keys

Returns the list of known API Keys and their description/permissions.

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2/keys
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bf2439319ea",
  "method": "users/self/keys",
  "response": {
    "F4C108DA-4070-45A4-8223-8C5DDFB96A51": {
      "description": "Test Key",
      "domains_read": "true",
      "domains_write": "true",
      "user_read": "true",
      "user_write": "true"
    },
    "60B56841-508D-4037-9A16-B234B9E849A0": {
      "description": "Domains Read-Only Key",
      "domains_read": "true",
      "domains_write": "false",
      "user_read": "false",
      "user_write": "false"
    }
  }
}

Create a new Key
POST/users/{userid}/keys

Create a new API Key. The key itself will be randomly generated and returned.

Example URI

POST https://api.mydnshost.co.uk/1.0/users/2/keys
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Request  Create a key that has read-only access to just /domains
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "description": "Domains Read-Only Key",
    "domains_read": "true"
  }
}
Response  200
HideShow

The response on success will show the newly created key

Headers
Content-Type: application/json
Body
{
  "respid": "58bf24e7d5638",
  "method": "users/self/keys",
  "response": {
    "60B56841-508D-4037-9A16-B234B9E849A0": {
      "description": "Domains Read-Only Key",
      "domains_read": "true",
      "domains_write": false,
      "user_read": false,
      "user_write": false,
      "updated": true
    }
  }
}

Manipulate specific API Key

Get key description/permissions
GET/users/{userid}/keys/{keyid}

Example URI

GET https://api.mydnshost.co.uk/1.0/users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 00413A9B-E086-4AD7-AC82-FF061B28D176

The key ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bf257073446",
  "method": "users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176",
  "response": {
    "description": "Domains Read-Only Key",
    "domains_read": "true",
    "domains_write": "false",
    "user_read": "false",
    "user_write": "false"
  }
}

Update key
POST/users/{userid}/keys/{keyid}

This takes the same parameters as create, but will update an existing key.

Example URI

POST https://api.mydnshost.co.uk/1.0/users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 00413A9B-E086-4AD7-AC82-FF061B28D176

The key ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "description": "Full-Access Key",
    "domains_read": "true",
    "domains_write": "true",
    "user_read": "true",
    "user_write": "true"
  }
}
Response  200
HideShow

The response on success will show the key as it exists after the change.

Headers
Content-Type: application/json
Body
{
  "respid": "58bf24e7d5638",
  "method": "users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176",
  "response": {
    "description": "Full-Access Key",
    "domains_read": "true",
    "domains_write": "true",
    "user_read": "true",
    "user_write": "true",
    "updated": true
  }
}

Delete key
DELETE/users/{userid}/keys/{keyid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 00413A9B-E086-4AD7-AC82-FF061B28D176

The key ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bf2602687cc",
    "method": "users/self/keys/00413A9B-E086-4AD7-AC82-FF061B28D176",
    "response":[
       "deleted": "true"
    ]
}

2FA Keys

Get known 2FA Keys
GET/users/{userid}/2fa

Returns the list of known 2FA Key-IDs and information about them.

Keys that have not yet been verified will also include the secret to allow a QR Code to be displayed.

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2/2fa
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "591e43446c4b7",
  "method": "users/self/2fa",
  "response": {
    "1": {
      "description": "Test Key",
      "created": "1495151997",
      "lastused": "1495153158",
      "active": "true"
    },
    "2": {
      "key": "MCOERRKFPJ7Z2Q2U",
      "description": "Second Key",
      "created": "1495151997",
      "lastused": "0",
      "active": "false"
    }
  }
}

Create a new Key
POST/users/{userid}/2fa

Create a new 2FA Key. The secret for the key will be randomly generated and included in the returned output.

Example URI

POST https://api.mydnshost.co.uk/1.0/users/2/2fa
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Request  Create a key
HideShow
Headers
Content-Type: application/json
Body
{
    "data": {
        "description": "Third Key",
    }
}
Response  200
HideShow

The response on success will show the newly created key

Headers
Content-Type: application/json
Body
{
  "respid": "591e43b1d0df7",
  "method": "users/self/2fa",
  "response": {
    "id": "6",
    "key": "7QEAT6ARPO4TKVUC",
    "description": "Third Key",
    "created": 1495155633,
    "lastused": 0,
    "active": false,
    "updated": true
  }
}

Manipulate specific 2FA Key

Get key description/permissions
GET/users/{userid}/2fa/{keyid}

Example URI

GET https://api.mydnshost.co.uk/1.0/users/self/2fa/6
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 6

The key ID.

Response  200
HideShow

The “key” parameter will only be returned if the key is not yet active.

Headers
Content-Type: application/json
Body
{
  "respid": "591e43f5ce743",
  "method": "users/self/2fa/6",
  "response": {
    "id": "6",
    "key": "7QEAT6ARPO4TKVUC",
    "description": "Third Key",
    "created": "1495155633",
    "lastused": "0",
    "active": "false"
  }
}

Update key
POST/users/{userid}/2fa/{keyid}

This takes the same parameters as create, but will update an existing key.

Example URI

POST https://api.mydnshost.co.uk/1.0/users/self/2fa/6
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 6

The key ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "description": "Third Device"
  }
}
Response  200
HideShow

The response on success will show the key as it exists after the change. The “key” parameter will only be returned if the key is not yet active.

Headers
Content-Type: application/json
Body
{
  "respid": "591e444c2868c",
  "method": "users/self/2fa/6",
  "response": {
    "id": "6",
    "key": "7QEAT6ARPO4TKVUC",
    "description": "Third Device",
    "created": "1495155633",
    "lastused": "0",
    "active": "false",
    "updated": true
  }
}

Delete key
DELETE/users/{userid}/2fa/{keyid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/self/2fa/6
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 6

The key ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "591e456fdb62f",
    "method": "users/self/2fa/6",
    "response":[
        "deleted": "true"
    ]
}

Verify 2FA Key

Verify 2FA Key
POST/users/{userid}/2fa/{keyid}/verify

Example URI

POST https://api.mydnshost.co.uk/1.0/users/self/2fa/6/verify
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

keyid
string (required) Example: 6

The key ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "123456"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "591e453d08ac9",
  "method": "users/self/2fa/6/verify",
  "response": {
    "success": "Valid code provided."
  }
}
Response  40 01
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "591e455409613",
  "method": "users/self/2fa/6/verify",
  "error": "Invalid code provided for verification."
}

2FA Devices

2FA Devices are devices that have passed the 2FA check in the past and the user has chosen to allow them to login without 2fa.

Get known 2FA Devices
GET/users/{userid}/2fadevices

Returns the list of known 2FA Devices and information about them.

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2/2fadevices
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "5a1af9caaffc6",
    "method": "users/self/2fadevices",
    "response":{
        "1":{
            "description": "Some Device",
            "created": "1511715554",
            "lastused": "1511715554",
        },
        "2":{
            "description": "Some Other Device",
            "current": true,
            "created": "1511717965",
            "lastused": "1511717965",
        }
    }
}

Manipulate specific 2FA Device

Delete key
DELETE/users/{userid}/2fadevices/{deviceid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/self/2fadevices/6
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

deviceid
string (required) Example: 6

The Device ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "5a1afd4852d97",
    "method": "users/self/2fadevices/6",
    "response":[
        "deleted": "true"
    ]
}

User custom data

This allows applications to store user-specific data within the api.

Get known custom data
GET/users/{userid}/customdata

Returns the list of known Custom-Data Key/Value pairs.

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2/customdata
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "59c7bac0c46e5",
  "method": "users/self/customdata",
  "response": {
    "test.ing": "testValue 2",
    "test.ing3": "testValue 3",
    "uk.co.mydnshost.www/domain/defaultpage": "records"
  }
}

Manipulate specific custom data key/value

Get key valie
GET/users/{userid}/customdata/{key}

Example URI

GET https://api.mydnshost.co.uk/1.0/users/self/customdata/test.ing
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

key
string (required) Example: test.ing

The custom data key.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "59c7baf524aac",
  "method": "users/self/customdata/test.ing",
  "response": {
    "key": "test.ing",
    "value": "testValue 2"
  }
}

Create/Update custom data for key
POST/users/{userid}/customdata/{key}

Example URI

POST https://api.mydnshost.co.uk/1.0/users/self/customdata/test.ing
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

key
string (required) Example: test.ing

The custom data key.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "value": "Some Value"
  }
}
Response  200
HideShow

The response on success will show the data as it exists after the change.

Headers
Content-Type: application/json
Body
{
  "respid": "59c7bb169ac68",
  "method": "users/self/customdata/test.ing",
  "response": {
    "key": "test.ing",
    "value": "Some Value",
    "updated": true
  }
}

Delete key
DELETE/users/{userid}/customdata/{key}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/users/self/customdata/test.ing
URI Parameters
HideShow
userid
string (required) Example: self

The user ID. This can also be “self” for the current user.

key
string (required) Example: test.ing

The custom data key.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "59c7bb2d0cfd5",
    "method": "users/self/customdata/test.ing"
    "response":[
        "deleted": "true"
    ]
}

User Domain Statistics

Get statistics for all our domains
GET/users/{userid}/stats/{stattype}{?type}

Example URI

GET https://api.mydnshost.co.uk/1.0/users/2/stats/domains?type=raw
URI Parameters
HideShow
userid
string (required) Example: 2

The user ID. This can also be “self” for the current user.

stattype
string (required) Example: domains
type
string (required) Example: raw
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "59c7c79a96fd3",
    "method": "/users/self/stats/domains",
    "response":{
        "stats": {
            "example.org": [{"time": 1505074560, "value": 249101},
                            {"time": 1505074620, "value": 249122},
                            {"time": 1505074680, "value": 249132},
                            // More data
                            {"time": 1505078040, "value": 250476},
                            {"time": 1505078100, "value": 250497}],
            "example.com": [{"time": 1505074560, "value": 97971},
                            {"time": 1505074620, "value": 97975},
                            {"time": 1505074680, "value": 97975},
                            // More data
                            {"time": 1505078040, "value": 98409},
                            {"time": 1505078100, "value": 98409}],
            // More Domain Names
            "example.net": [{"time": 1505074560, "value": 176},
                            {"time": 1505074620, "value": 176},
                            {"time": 1505074680, "value": 176},
                            // More data
                            {"time": 1505078040, "value": 176},
                            {"time": 1505078100, "value": 176}]
        }
    }
}

Domains

Endpoints for dealing with domains.

Get domains

Get list of known domains
GET/domains{?contains}

See what domains you have access to, and what level of access to each.

Example URI

GET https://api.mydnshost.co.uk/1.0/domains?contains=foo.bar.baz.example.com
URI Parameters
HideShow
contains
string (optional) Example: foo.bar.baz.example.com

Only return the domain that would contain this record

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc0357e7eb",
  "method": "domains",
  "response": {
    "example.org": "owner",
    "test2.com": "owner",
    "example1.org": "write",
    "example2.org": "read"
  }
}

Create a new domain
POST/domains

If the user has the domains_create permission, they can use this to create a new domain owned by themselves.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains
Request  Create a domain
HideShow
Headers
Content-Type: application/json
Body
{
    "data": {
        "domain": "example.net",
    }
}
Response  200
HideShow

A successful response will display the newly-created domain.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc0c377913",
  "method": "domains",
  "response": {
    "id": "9",
    "domain": "example.net",
    "defaultttl": 86400,
    "disabled": false,
    "SOA": {
      "primaryNS": "ns1.example.net.",
      "adminAddress": "dnsadmin.example.net.",
      "serial": "0",
      "refresh": "86400",
      "retry": "7200",
      "expire": "2419200",
      "minttl": "60"
    }
  }
}
Response  400
HideShow

An error will include an error and possibly errorData information.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc115b3601",
  "method": "domains",
  "error": "Error updating domain.",
  "errorData": "Domain already exists."
}

Specific domain infomation

Get information about a domain
GET/domains/{domain}

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow

A successful response will display information about the domain.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc18455fac",
  "method": "domains/example.org",
  "response": {
    "id": "3",
    "domain": "example.org",
    "defaultttl": 86400,
    "disabled": "false",
    "SOA": {
      "primaryNS": "ns1.mydnshost.co.uk.",
      "adminAddress": "dnsadmin.dataforce.org.uk.",
      "serial": "2017030500",
      "refresh": "86400",
      "retry": "7200",
      "expire": "2419200",
      "minttl": "60"
    }
  }
}
Response  400
HideShow

An error will include an error rather than the response

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc1a902ddd",
  "method": "domains/example.example",
  "error": "Unknown domain: example.example"
}

Update information about a domain
POST/domains/{domain}

This allows changing the domain enabled/disabled status or updating the SOA fields.

As with other update methods, only fields that are provided will be changed, you do not need to provide a complete object.

Changes made with this end point do not automatically increment the domain serial.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  Disable domain and update the serial
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "disabled": "true",
    "SOA": {
      "serial": "999"
    }
  }
}
Response  200
HideShow

A successful response will display the newly-updated domain.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc2a9b4b77",
  "method": "domains/example.org",
  "response": {
    "id": "3",
    "domain": "example.org",
    "defaultttl": 86400,
    "disabled": "true",
    "SOA": {
      "primaryNS": "ns1.mydnshost.co.uk.",
      "adminAddress": "dnsadmin.dataforce.org.uk.",
      "serial": "999",
      "refresh": "86400",
      "retry": "7200",
      "expire": "2419200",
      "minttl": "60"
    }
  }
}

Delete a domain
DELETE/domains/{domain}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bcc2d6e7515",
    "method": "domains/example.org",
    "response":[
       "deleted": "true"
    ]
}

Domain access levels

Get all users with access to the domain
GET/domains/{domain}/access

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/access
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bdf7472d255",
  "method": "domains/example2.org/access",
  "response": {
    "id": "7",
    "domain": "example2.org",
    "defaultttl": 86400,
    "disabled": "false",
    "access": {
      "admin@example.org": "write",
      "user2@example.org": "owner"
    }
  }
}

Update domain access
POST/domains/{domain}/access

This allows changing user access levels on the domain.

As a general rule of thumb, you can not edit your own access level, and you can not set people to have an access level equal or above your own (Thus only users with the manage_domains permission can set domain owners.)

There are 5 levels of access (each level has all the access of those below it):

  • owner - Owner has full control over the domain, there can only be 1. Only the owner can delete the domain.

  • admin - Domain admins can grant other users write access to the domain.

  • write - Write allows changing domain records

  • read - Read allows reading domain records but not changing

  • none - No access to the domain (Default)

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/access
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  Give user1 write access
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "access": {
      "user1@example.org": "write"
    }
  }
}
Response  200
HideShow

A successful response will display the newly-updated access list.

Headers
Content-Type: application/json
Body
{
  "respid": "58bdf89ebc587",
  "method": "domains/example2.org/access",
  "response": {
    "id": "7",
    "domain": "example2.org",
    "defaultttl": 86400,
    "disabled": "false",
    "access": {
      "admin@example.org": "write",
      "user2@example.org": "owner",
      "user1@example.org": "write"
    }
  }
}
Response  400
HideShow

If there is an error changing any of the requested access, the whole change will be aborted with an error message explaining why.

Headers
Content-Type: application/json
Body
{
  "respid": "58bdf83ed6cd5",
  "method": "domains/example2.org/access",
  "error": "You do not have the required access to the domain: example2.org"
}

Domain Keys

Get known Domain Keys
GET/domains/{domain}/keys

Returns the list of known Domain Keys and their description/permissions.

Domain keys behave like user API Keys, except they are limited to a single domain and can only be given read or write access (not owner or admin).

You will need write level access on a domain to view or make changes to domain keys and will need to be authenticated as a real user and not using another domain key.

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/keys
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "592f821198f95",
  "method": "domains/example.org/keys",
  "response": {
    "9426F536-2559-4FA0-BA50-644C90B5FAE4": {
      "description": "Write Key",
      "domains_write": "true",
      "created": "1496284877",
      "lastused": "1496284879"
    },
    "586DAB85-9DCE-4FA2-AA9D-877AA7011190": {
      "description": "Read Key",
      "domains_write": "false",
      "created": "1496284877",
      "lastused": "1496285565"
    }
  }
}

Create a new Key
POST/domains/{domain}/keys

Create a new Domain Key. The key itself will be randomly generated and returned.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/keys
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  Create a key that has read-only access
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "description": "Read-Only Key"
  }
}
Response  200
HideShow

The response on success will show the newly created key

Headers
Content-Type: application/json
Body
{
  "respid": "592f825565d61",
  "method": "domains/example.org/keys",
  "response": {
    "7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E": {
      "description": "Read-Only Key",
      "domains_write": false,
      "created": 1496285781,
      "lastused": 0,
      "updated": true
    }
  }
}

Manipulate specific Domain Key

Get key description/permissions
GET/domains/{domain}/keys/{keyid}

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

keyid
string (required) Example: 7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E

The key ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "592f828d6ddbd",
  "method": "domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E",
  "response": {
    "description": "Read-Only Key",
    "domains_write": "false",
    "created": "1496285781",
    "lastused": "0"
  }
}

Update key
POST/domains/{domain}/keys/{keyid}

This takes the same parameters as create, but will update an existing key.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

keyid
string (required) Example: 7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E

The key ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "description": "Full-Access Key",
    "domains_write": "true"
  }
}
Response  200
HideShow

The response on success will show the key as it exists after the change.

Headers
Content-Type: application/json
Body
{
  "respid": "592f82ac75e21",
  "method": "domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E",
  "response": {
    "description": "Full-Access Key",
    "domains_write": "true",
    "created": "1496285781",
    "lastused": "0",
    "updated": true
  }
}

Delete key
DELETE/domains/{domain}/keys/{keyid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

keyid
string (required) Example: 7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E

The key ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "592f82c0d3006",
    "method": "domains/example.org/keys/7BACDD7D-31D2-4B01-9D8B-D782CD71BF0E",
    "response":[
       "deleted": "true"
    ]
}

Domain Hooks

Get known Domain Hooks
GET/domains/{domain}/hooks

Returns the list of known Domain Hooks and any password associated with them

Domain Hooks are web pages that recieve specially-crafted POST requests when certain events happen related to a domain.

If a password is specified, the POST request will include an X-HMAC-SIGNATURE header signing the data that was sent.

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/hooks
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "5a1afee40bc4c",
  "method": "domains/example.org/hooks",
  "response": {
    "3": {
      "url": "http://hooks.example.org/hook1.php",
      "password": "password",
      "disabled": "false",
      "created": "1511718537",
      "lastused": "0"
    },
    "4": {
      "url": "http://hooks.example.org/hook2.php",
      "password": "",
      "disabled": "false",
      "created": "1511718542",
      "lastused": "0"
    }
  }
}

Create a new Hook
POST/domains/{domain}/hooks

Create a new Domain Hook.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/hooks
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  Create a Hook without a password
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "url": "http://hooks.example.org/hook3.php",
    "password": ""
  }
}
Response  200
HideShow

The response on success will show the newly created hook

Headers
Content-Type: application/json
Body
{
    "respid": "5a1b003293d16",
    "method": "domains/example.org/hooks",
    "response":{
        "5":{
            "url": "http://hooks.example.org/hook3.php",
            "password": "",
            "disabled": false,
            "created": 1511718962,
            "lastused": 0,
            "updated": true
            }
        }
    }
}

Manipulate specific Domain Hook

Get Hook details
GET/domains/{domain}/hooks/{hookid}

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/hooks/5
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

hookid
string (required) Example: 5

The Hook ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "592f828d6ddbd",
  "method": "domains/example.org/hooks/5",
  "response": {
    "url": "http://hooks.example.org/hook3.php",
    "password": "",
    "disabled": false,
    "created": 1511718962,
    "lastused": 0
  }
}

Update Hook
POST/domains/{domain}/hooks/{hookid}

This takes the same parameters as create, but will update an existing hook.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/hooks/5
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

hookid
string (required) Example: 5

The Hook ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "password": "foo"
  }
}
Response  200
HideShow

The response on success will show the hook as it exists after the change.

Headers
Content-Type: application/json
Body
{
  "respid": "5a1b00d645f22",
  "method": "domains/example.org/hooks/5",
  "response": {
    "url": "http://hooks.example.org/hook3.php",
    "password": "foo",
    "disabled": "false",
    "created": "1511718900",
    "lastused": "0",
    "updated": true
  }
}

Delete Hook
DELETE/domains/{domain}/hooks/{hookid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org/hooks/5
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

hookid
string (required) Example: 5

The Hook ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "592f82c0d3006",
    "method": "domains/example.org/hooks/5",
    "response":[
       "deleted": "true"
    ]
}

Domain records

Get all domain records
GET/domains/{domain}/records

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/records
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc3059365b",
  "method": "domains/example.org/records",
  "response": {
    "records": [
      {
        "id": "18",
        "name": "",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "19",
        "name": "www",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "20",
        "name": "",
        "type": "AAAA",
        "content": "::1",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "21",
        "name": "www",
        "type": "AAAA",
        "content": "::1",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "22",
        "name": "txt",
        "type": "TXT",
        "content": "Some Text Record",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "23",
        "name": "",
        "type": "MX",
        "content": "",
        "ttl": "86400",
        "priority": "10",
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      },
      {
        "id": "24",
        "name": "",
        "type": "MX",
        "content": "test",
        "ttl": "86400",
        "priority": "50",
        "changed_at": "1488755309",
        "changed_by": null,
        "disabled": "false"
      }
    ],
    "soa": {
      "primaryNS": "ns1.mydnshost.co.uk.",
      "adminAddress": "dnsadmin.dataforce.org.uk.",
      "serial": "999",
      "refresh": "86400",
      "retry": "7200",
      "expire": "2419200",
      "minttl": "60"
    }
  }
}

Update domain records
POST/domains/{domain}/records

This can update/delete specifically named records, or add new records all in one go.

You can not edit the SOA from here, and the serial will be incremented automatically.

As with other update methods, only fields that are provided will be changed, you do not need to provide a complete object.

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/records
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  update content for ID 18/19, delete 20 and add a new A record.
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "records": [
      {
        "id": "18",
        "content": "127.0.0.18"
      },
      {
        "id": "19",
        "content": "127.0.0.18"
      },
      {
        "id": "20",
        "delete": true
      },
      {
        "name": "localhost",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": "86400"
      }
    ]
  }
}
Response  200
HideShow

A success response will show the records that were changed, and any new records that were added, along with the new domain serial.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc593acecc",
  "method": "domains/example.org/records",
  "response": {
    "serial": "2017030600",
    "changed": [
      {
        "id": "18",
        "name": "",
        "type": "A",
        "content": "127.0.0.18",
        "ttl": "86400",
        "priority": null,
        "changed_at": 1488766355,
        "changed_by": "2",
        "disabled": "false",
        "updated": true
      },
      {
        "id": "19",
        "name": "www",
        "type": "A",
        "content": "127.0.0.18",
        "ttl": "86400",
        "priority": null,
        "changed_at": 1488766355,
        "changed_by": "2",
        "disabled": "false",
        "updated": true
      },
      {
        "id": "35",
        "name": "localhost",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": "86400",
        "priority": null,
        "changed_at": 1488766355,
        "changed_by": "2",
        "disabled": false,
        "updated": true
      },
      {
        "id": "20",
        "deleted": true
      }
    ]
  }
}
Response  400
HideShow

A response will contain errorData to show errors related to specific records passed in. If there are any errors, no changes are made.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc54aca077",
  "method": "domains/example.org/records",
  "error": "There was errors with the records provided.",
  "errorData": {
    "1": "Unable to validate record: Content must be a valid IPv4 Address."
  }
}

Delete all domain records
DELETE/domains/{domain}/records

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org/records
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc5e696495",
  "method": "domains/example.org/records",
  "response": {
    "deleted": 7,
    "serial": 2017030601
  }
}

Domain Statistics

Get raw statistics for this domain
GET/domains/{domain}/stats{?type}

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/stats?type=raw
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

type
string (required) Example: raw
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "59b5900b12a2e",
    "method": "domains/example.org/stats",
    "response":{
        "stats": {
            "A": [{"time": 1505074560, "value": 249101},
                  {"time": 1505074620, "value": 249122},
                  {"time": 1505074680, "value": 249132},
                  // More data
                  {"time": 1505078040, "value": 250476},
                  {"time": 1505078100, "value": 250497}],
            "AAAA": [{"time": 1505074560, "value": 97971},
                     {"time": 1505074620, "value": 97975},
                     {"time": 1505074680, "value": 97975},
                     // More data
                     {"time": 1505078040, "value": 98409},
                     {"time": 1505078100, "value": 98409}],
            // More RR Types
            "TXT": [{"time": 1505074560, "value": 176},
                    {"time": 1505074620, "value": 176},
                    {"time": 1505074680, "value": 176},
                    // More data
                    {"time": 1505078040, "value": 176},
                    {"time": 1505078100, "value": 176}]
        }
    }
}

Domain export

Export zone as bind zone file
GET/domains/{domain}/export

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/export
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58cef4d2a5104",
  "method": "domains/example.org/export",
  "response": {
    "zone": "; Written at Sun, 19 Mar 2017 21:14:58 +0000\n$TTL 86400\n$ORIGIN example.org.\nexample.org. IN SOA ns1.example.org. dnsadmin.example.org. (\n 2017031900\n 86400\n 7200\n 2419200\n 60 )\n\nexample.org. 86400 IN NS dev.mydnshost.co.uk.\nexample.org. 86400 IN A 127.0.0.1\nwww.example.org. 86400 IN A 127.0.0.1\nexample.org. 86400 IN AAAA ::1\nwww.example.org. 86400 IN AAAA ::1\ntest.example.org. 86400 IN CNAME www.example.org.\ntxt.example.org. 86400 IN TXT \"Some Text Record\"\nexample.org. 86400 IN MX 10 example.org.\nexample.org. 86400 IN MX 50 www.example.org.\n"
  }
}

Domain import

Export zone as bind zone file
POST/domains/{domain}/import

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/import
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Request  import from zone file
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "zone": "; Written at Sun, 19 Mar 2017 21:14:58 +0000\n$TTL 86400\n$ORIGIN example.org.\nexample.org. IN SOA ns1.example.org. dnsadmin.example.org. (\n 2017031900\n 86400\n 7200\n 2419200\n 60 )\n\nexample.org. 86400 IN NS dev.mydnshost.co.uk.\nexample.org. 86400 IN A 127.0.0.1\nwww.example.org. 86400 IN A 127.0.0.1\nexample.org. 86400 IN AAAA ::1\nwww.example.org. 86400 IN AAAA ::1\ntest.example.org. 86400 IN CNAME www.example.org.\ntxt.example.org. 86400 IN TXT \"Some Text Record\"\nexample.org. 86400 IN MX 10 example.org.\nexample.org. 86400 IN MX 50 www.example.org.\n"
  }
}
Response  200
HideShow

If the import is successful, the zone serial will be returned.

Headers
Content-Type: application/json
Body
{
  "respid": "58cef5a9d7216",
  "method": "domains/example.org/import",
  "response": {
    "serial": "2017031900"
  }
}

Specific domain record information

Get specific record information
GET/domains/{domain}/records/{recordid}

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/records/21
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

recordid
number (required) Example: 21

The record id

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc673f3c17",
  "method": "domains/example.org/records/21",
  "response": {
    "id": "21",
    "name": "www",
    "type": "A",
    "content": "127.0.0.1",
    "ttl": "86400",
    "priority": null,
    "changed_at": "1488766474",
    "changed_by": null,
    "disabled": "false"
  }
}

Update a specific record
POST/domains/{domain}/records/{recordid}

Example URI

POST https://api.mydnshost.co.uk/1.0/domains/example.org/records/21
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

recordid
number (required) Example: 21

The record id

Request  Update content
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "content": "127.0.0.18"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc6cb79998",
  "method": "domains/example.org/records/21",
  "response": {
    "id": "21",
    "name": "www",
    "type": "A",
    "content": "127.0.0.18",
    "ttl": "86400",
    "priority": null,
    "changed_at": 1488766667,
    "changed_by": "2",
    "disabled": "false"
  }
}
Response  400
HideShow

If there is a validation error, you will get error and errorData rather than response

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc6df9bd2d",
  "method": "domains/example.org/records/21",
  "error": "Error updating record.",
  "errorData": "Content must be a valid IPv4 Address."
}

Delete a specific record
DELETE/domains/{domain}/records/{recordid}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org/records/21
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

recordid
number (required) Example: 21

The record id

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc701e70d7",
  "method": "domains/example.org/records/21",
  "response": {
    "deleted": "true",
    "serial": 2017030601
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "58bcc75e10e3a",
  "method": "domains/example.org/records/21",
  "error": "Unknown record id for domain example.org : 21"
}

Specific records by name

Get all `www` records with a type of A
GET/domains/{domain}/record/{rrname}/{rrtype}

This allows looking at specific records by name and/or type.

(If rrtype is not specified, then all records of the requested name will be shown, regardless of the type)

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/record/www/A
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

rrname
string (required) Example: www

The record name

rrtype
string (optional) Example: A

The record type

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "591b5190e3f66",
  "method": "domains/example1.org/record/www/A",
  "response": {
    "records": [
      {
        "id": "69",
        "name": "www",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": "86400",
        "priority": null,
        "changed_at": "1490399322",
        "changed_by": null,
        "disabled": "false"
      }
    ]
  }
}

Delete all domain records with a type of A
DELETE/domains/{domain}/record/{rrname}/{rrtype}

Example URI

DELETE https://api.mydnshost.co.uk/1.0/domains/example.org/record/www/A
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

rrname
string (required) Example: www

The record name

rrtype
string (optional) Example: A

The record type

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "respid": "591b51c5a5ca8",
  "method": "domains/example1.org/record/www/A",
  "response": {
    "deleted": 1,
    "serial": "2017051600"
  }
}

Force backend sync

Force backend sync
GET/domains/{domain}/sync

Attempt to resync the domain with the server backends.

This can be used to force the server backend to refresh its copy of the domain without needing to make any changes.

Example URI

GET https://api.mydnshost.co.uk/1.0/domains/example.org/sync
URI Parameters
HideShow
domain
string (required) Example: example.org

The domain name

Response  200
HideShow

This will always show a successful response, it only fires the sync hook.

Headers
Content-Type: application/json
Body
{
  "respid": "58cef6194ca63",
  "method": "domains/example.org/sync"
}

Domains Admin

Admin Endpoints for dealing with domains, end points under /admin require the manage_domains permission.

As a general rule, anything that exists under /domains also exists under /admin/domains but in a less-restricted fashion. (ie, behaves as if the user had owner access to all domains and allows setting the domain owner access level on a domain).

As such, to prevent documentation duplication, this section only lists methods where the result is different.

Get domains

Get list of all known domains
GET/admin/domains

See what domains exist and user access levels for each.

Example URI

GET https://api.mydnshost.co.uk/1.0/admin/domains
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "58bdf3b15c33b",
    "method": "admin/domains",
    "response":{
        "example.org":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "test2.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "test3.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "test4.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "test5.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "example1.org":{
            "disabled": "false",
            "users":{
                "user1@example.org": "owner"
            }
        },
        "example2.org":{
        "disabled": "false",
            "users":{
                "admin@example.org": "write",
                "user2@example.org": "owner"
            }
        },
        "example3.org":{
            "disabled": "false",
            "users":{
                "user3@example.org": "owner"
            }
        },
        "example4.org":{
            "disabled": "false",
            "users":{
                "admin@example.org": "write",
                "user4@example.org": "owner"
            }
        },
        "example5.org":{
            "disabled": "false",
            "users":{
                "user5@example.org": "owner"
            }
        },
        "unowned1.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "owner"
            }
        },
        "unowned2.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "read"
            }
        },
        "unowned3.com":{
            "disabled": "false",
            "users":{
                null
            }
        },
        "unowned4.com":{
            "disabled": "false",
            "users":{
                "admin@example.org": "read"
            }
        },
        "unowned5.com":{
            "disabled": "false",
            "users":{
                null
            }
        }
    }
}

Create a new domain
POST/admin/domains

This behaves the same as the non-admin end-point, and requires the domains_create permission in addition to the manage_domains permission.

The admin version of the endpoint however also allows specifying an owner of a newly created domain.

If owner is not specified, then the current user will be set as the owner (same as non-admin end-point)

If owner is blank, no owner will be set.

Example URI

POST https://api.mydnshost.co.uk/1.0/admin/domains
Request  Create a domain
HideShow
Headers
Content-Type: application/json
Body
{
    "data": {
        "domain": "example.net",
        "owner": "someone@example.net",
    }
}
Response  200
HideShow

A successful response will display the newly-created domain.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc0c377913",
  "method": "domains",
  "response": {
    "id": "9",
    "domain": "example.net",
    "disabled": false,
    "SOA": {
      "primaryNS": "ns1.example.net.",
      "adminAddress": "dnsadmin.example.net.",
      "serial": "0",
      "refresh": "86400",
      "retry": "7200",
      "expire": "2419200",
      "minttl": "60"
    }
  }
}
Response  400
HideShow

An error will include an error and possibly errorData information.

Headers
Content-Type: application/json
Body
{
  "respid": "58bcc115b3601",
  "method": "domains",
  "error": "Error updating domain.",
  "errorData": "Duplicate entry 'example.net' for key 'domain_domain_unique'"
}

System

Endpoints for dealing with system internals.

Whilst every effort will be made to keep the API stable, resources available under this endpoint are subject to change without warning as required.

System Information

Get system datavalues from the API
GET/system/datavalue/{datavalue}

This lets you get system datavalues from the api. These are mostly used by the frontend to allow it to dynamically adapt to certain backend changes.

Some datavalues require authentication, some do not.

Example URI

GET https://api.mydnshost.co.uk/1.0/system/datavalue/validPermissions
URI Parameters
HideShow
datavalue
string (required) Example: validPermissions

The datavalue to get.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "59b5f1440fca4",
    "method": "system/datavalue/validPermissions",
    "response":{
    "validPermissions":[
        "domains_stats",
        "manage_domains",
        "domains_create",
        "manage_users",
        "manage_permissions",
        "impersonate_users"
    ]
}

System Statistics

Get system statistics from the API
GET/system/stats/{stat}{?type}

This lets you get system-level statistics from the api.

Example URI

GET https://api.mydnshost.co.uk/1.0/system/stats/queries-per-server?type=raw
URI Parameters
HideShow
stat
string (required) Example: queries-per-server

The statistic to get (queries-per-server, queries-per-rrtype, queries-per-zone).

type
string (optional) Example: raw

Type of stats (raw or derivative)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "respid": "59b5faf590931",
    "method": "system/stats/queries-per-server",
    "response":{
        "stats":{
            "ns1":[
                {"time": 1505094900, "value": 18},
                {"time": 1505094960, "value": 26},
                {"time": 1505095020, "value": 28},
                // More Stats
                {"time": 1505098380, "value": 23},
                {"time": 1505098440, "value": 8}
            ],
            // More Servers
            "ns4":[
                {"time": 1505094900, "value": 14},
                {"time": 1505094960, "value": 18},
                {"time": 1505095020, "value": 28},
                // More Stats
                {"time": 1505098380, "value": 28},
                {"time": 1505098440, "value": 6}
            ]
}

Generated by aglio on 13 Sep 2018