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"
}
]