API

LuaDNS allows you to edit your zones and records through a simple REST API. The API can be accessed only through HTTPS and all requests must be authenticated. The authentication method used by the API is standard HTTP Basic Authentication. The server accepts and sends data in JSON format only, all requests should set the Accept header to application/json.

By default API access is disabled, you should enable API first from the settings page if you plan to use it.

Security

An API key can be configured to be global with access to all zones or restricted to a single zone.

Client Libraries

URL

Current version of the API is v1, the API URL is:

https://api.luadns.com/v1

Authentication

To access the endpoints the client needs to authenticate using HTTP Basic Authentication. This is a simple authentication scheme built in the HTTP protocol. To authenticate you need a username and password.

* Username: Your email
* Password: Your API key

You can get your API key from the API Keys page.

Server Request

Filtering

The filtering makes possible to return a subset of records which matches a search query.

Parameters:

query - Query string (string, optional)

Sorting

To set sorting preferences use sort_by and sort_order parameters. The sort_order parameter can be asc for ascending order or desc for descending order.

sort_by - Sort column (string, optional)

sort_order - Sort order (string, optional, default: asc)

Pagination

Endpoints returning a list of items can use pagination to avoid large responses.

Parameters:

limit - Limit the number of returned results (integer, optional, default: 0)

page - The current page (integer, optional, default: 1)

The response will return pagination information via HTTP headers:

x-page: 1
x-limit: 30
x-total-pages: 1
x-total-count: 25

Server Response

Status Codes

The server will return HTTP 200 status code on successful operations, on errors returns:

HTTP/1.1 <StatusCode>
...
{
  "status": "<StatusMessage>",
  "request_id": "<RequestID>",
  "message": "<UserMessage>"
}

Status codes:

400 - Bad Request (validation error)
429 - Too Many Requests (rate-limited)
401 - Unauthorized (authentication failed)
403 - Forbidden (operation not allowed)
404 - Not Found (resource not found)
500 - Internal Server Error (should be retried later)

Rate Limiting

To prevent abuses the API requests are rate-limited to 1200 requests every 5 minutes. When the requests limit is reached the server responds with 429 status code. The rate-limited client should inspect the X-Ratelimit-Reset HTTP header to find the Unix timestamp when the limit is going to be reset.

Example:

HTTP/1.0 429 Too Many Requests
[...]
x-ratelimit-limit: 1200
x-ratelimit-remaining: 1200
x-ratelimit-reset: 1317945600

In this example the client should not issue new requests before 2011-10-07 00:00:00 UTC.

Users

This endpoint allows you to get information about users.

Get settings

Get information about user associated with current API key.

GET /users/me

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/users/me

The server returns user information:

{
  "email": "joe@example.com",
  "name": "John Doe",
  "repo_uri": "",
  "api_enabled": true,
  "tfa": false,
  "deploy_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCnxpLnmNsKIAHuTED...\n",
  "ttl": 300,
  "package": "Free",
  "name_servers": [
    "ns1.luadns.net.",
    "ns2.luadns.net.",
    "ns3.luadns.net.",
    "ns4.luadns.net."
  ]
}

Zones

This endpoint allows you to list/add/get/delete your hosted zones.

List zones

List all your hosted zones:

GET /zones

List Options

query - Search text (string, optional)

sort_by - Order by column (string, optional)

sort_order - (string, asc/desc, optional)

limit - Limit (integer, 1..500, optional)

page - Page (integer, 1..n, optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones

The server returns an array with all account zones:

[
  {
    "id": 1,
    "name": "example.com",
    "synced": false,
    "queries_count": 0,
    "records_count": 3,
    "aliases_count": 0,
    "redirects_count": 0,
    "forwards_count": 0,
    "template_id": 0
  },
  {
    "id": 2,
    "name": "example.net",
    "synced": false,
    "queries_count": 0,
    "records_count": 3,
    "aliases_count": 0,
    "redirects_count": 0,
    "forwards_count": 0,
    "template_id": 0
  }
]

Create a zone

To create a new zone, submit your JSON encoded data using POST request:

POST /zones

Parameters:

name - Domain name (string, required)

template_id - Template ID (integer, optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X POST \
        -d '<json>' \
        https://api.luadns.com/v1/zones

On successful request the server returns the new zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 0,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0
}

Get a zone

To retrieve a zone by :id use:

GET /zones/:id

Parameters:

:id - Zone ID (integer)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/3

The server returns the zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 3,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0,
  "records": [
    {
      "id": 6683,
      "name": "example.org.",
      "type": "SOA",
      "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421501178 1200 120 604800 3600",
      "ttl": 3600,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.52747Z",
      "updated_at": "2015-01-17T13:26:17.527471Z"
    },
    {
      "id": 6684,
      "name": "example.org.",
      "type": "NS",
      "content": "a.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.529741Z",
      "updated_at": "2015-01-17T13:26:17.529741Z"
    },
    {
      "id": 6685,
      "name": "example.org.",
      "type": "NS",
      "content": "b.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.531911Z",
      "updated_at": "2015-01-17T13:26:17.531911Z"
    }
  ]
}

Update a zone

To update a zone, submit your JSON encoded data using PUT request:

PUT /zones/:id

Parameters:

:id - Zone ID (integer)

name - Domain name (string, required)

records - Array of records (optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X PUT \
        -d '<json>' \
        https://api.luadns.com/v1/zones/3

On successful request the server returns updated zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 3,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0,
  "records": [
    {
      "id": 6683,
      "name": "example.org.",
      "type": "SOA",
      "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421501190 1200 120 604800 3600",
      "ttl": 3600,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.52747Z",
      "updated_at": "2015-01-17T13:26:17.527471Z"
    },
    {
      "id": 6684,
      "name": "example.org.",
      "type": "NS",
      "content": "a.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.529741Z",
      "updated_at": "2015-01-17T13:26:17.529741Z"
    },
    {
      "id": 6685,
      "name": "example.org.",
      "type": "NS",
      "content": "b.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.531911Z",
      "updated_at": "2015-01-17T13:26:17.531911Z"
    }
  ]
}

Delete a zone

To delete a zone by :id use:

DELETE /zones/:id

Parameters:

:id - Zone ID (integer)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X DELETE \
        https://api.luadns.com/v1/zones/3

Server returns deleted zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 3,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0,
  "records": [
    {
      "id": 6683,
      "name": "example.org.",
      "type": "SOA",
      "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421501178 1200 120 604800 3600",
      "ttl": 3600,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.52747Z",
      "updated_at": "2015-01-17T13:26:17.527471Z"
    },
    {
      "id": 6684,
      "name": "example.org.",
      "type": "NS",
      "content": "a.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.529741Z",
      "updated_at": "2015-01-17T13:26:17.529741Z"
    },
    {
      "id": 6685,
      "name": "example.org.",
      "type": "NS",
      "content": "b.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.531911Z",
      "updated_at": "2015-01-17T13:26:17.531911Z"
    }
  ]
}

Zone Records

The records endpoint allows you to list/add/get/update/delete zone records.

List records

List all records for a zone:

GET /zones/:zone_id/records

Parameters:

:zone_id - Zone ID (integer, required)

List Options

query - Search text (string, optional)

sort_by - Order by column (string, optional)

sort_order - (string, asc/desc, optional)

limit - Limit (integer, 1..500, optional)

page - Page (integer, 1..n, optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/3

The server returns an array containing the records for zone :zone_id:

[
  {
    "id": 6683,
    "name": "example.org.",
    "type": "NS",
    "content": "b.ns.luadns.net.",
    "ttl": 86400,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.522452Z",
    "updated_at": "2015-01-17T13:08:37.522452Z"
  },
  {
    "id": 6684,
    "name": "example.org.",
    "type": "NS",
    "content": "a.ns.luadns.net.",
    "ttl": 86400,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.520623Z",
    "updated_at": "2015-01-17T13:08:37.520623Z"
  },
  {
    "id": 6685,
    "name": "example.org.",
    "type": "SOA",
    "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421500118 1200 120 604800 3600",
    "ttl": 3600,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.519019Z",
    "updated_at": "2015-01-17T13:08:37.519019Z"
  }
]

Create a record

To create a new record on zone identified by :zone_id POST your JSON encoded data:

POST /zones/:zone_id/records

Parameters:

:zone_id - Zone ID (integer)

name - name (string, required)

type - type (string, required)

content - content (string, required)

ttl - TTL (integer, optional)

external_id - identification text associated with an external record (string, optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X POST \
        -d '<json>' \
        https://api.luadns.com/v1/zones/1/records

The server will validates your input returns the new record on successful creation:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Get a record

To retrieve a record by :id from zone identified by :zone_id use:

GET /zones/:zone_id/records/:id

Parameters:

:zone_id - Zone ID (integer)

:id - Record ID (integer)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/1/records/100

The server returns the record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Update a record

To update a record :id from zone identified by :zone_id use:

PUT /zones/:zone_id/records/:id

Parameters:

:zone_id - Zone ID (integer)

:id - Record ID (integer)

name - name (string, required)

type - type (string, required)

content - content (string, required)

ttl - TTL (integer, optional)

external_id - identification text associated with an external record (string, optional)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X PUT \
        -d '<json>'
        https://api.luadns.com/v1/zones/1/records/100

The server returns the updated record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Delete a record

To delete a record by :id from zone identified by :zone_id use:

DELETE /zones/:zone_id/records/:id

Parameters:

:zone_id - Zone ID (integer)

:id - Record ID (integer)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        -X DELETE \
        https://api.luadns.com/v1/zones/1/records/100

The server returns deleted record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Zone DS Records

This endpoint allows you to list DS records for a zone.

List DS records

List DS records for a zone:

GET /zones/:zone_id/ds_records

Parameters:

:zone_id - Zone ID (integer)

Example:

$ curl -u <email>:<api_key> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/12345/ds_records

The server returns an array with all DS records:

[
   {
      "id" : 985,
      "key_tag" : 11821,
      "algorithm" : 13,
      "digest_type" : 2,
      "digest" : "e8550cbe1e954c9ee9c92c78cce5141f86a72fcb98a5bda570a5f6f0bbe6b16d",
      "public_key" : "P1uCOJQ/nYRDvN54D+ydiaUl8nwp6kH6YVtb4FgPbsl/tyh3SO1RtPvwAPYXKhJ8GS3mfhPUnk84MyFX1rmUDw==",
      "zone_id" : 12345,
      "created_at" : "2022-07-12T16:07:36Z",
      "updated_at" : "2022-07-12T16:07:36Z"
   }
]

Changelog

2024/09/02 - The ttl parameter was made optional when creating and updating records.
2024/08/15 - Extended API with filtering, sorting and pagination capabilities.

API

Security

Client Libraries

URL

Authentication

Server Request

Filtering

Sorting

Server Response

Status Codes

Rate Limiting

Users

Get settings

Zones

List zones

Create a zone

Get a zone

Update a zone

Delete a zone

Zone Records

List records

Create a record

Get a record

Update a record

Delete a record

Zone DS Records

List DS records

Changelog

About

Support

Contact