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 error 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 (malformed request)
  • 422 - Unprocesable Entity (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

The API requests are rate-limited to 1200 every 5 minutes.

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

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)

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, required)
  • 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, required)
  • 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"
   }
]