API Syntax

Introduction

Servercow provides its own API interface for all domain customers, which you can use to change DNS settings also via API call.

Basically the following URL is used to address the DNS API:

https://api.servercow.de/dns/v1/domains/example.org

Please note

example.org corresponds to the domain you want to address with the API.

The authentication is done in the header. Likewise, the Content-Type is explicitly specified here as application/json!

Content-Type: application/json
X-Auth-Username: servercow_username
X-Auth-Password: servercow_password

You will receive the API response in JSON format.

Compatibility

As of today, the API supports the following types: TXT, A, AAAA, CNAME, TLSA, CAA and MX - more will follow.

---

Examples

Example: Get active records of a domain via cURL

curl -X GET 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json'

In the above request we use the GET method. Except for the headers, we do not pass any data to the API.

Example: Create or edit a record of a domain via cURL

curl -X POST 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json' \
--data '{"type":"TXT","name":"_acme-challenge.www","content":"acbdefghijklmnopqrstuvwxyz","ttl":20}'

In the above request we use the POST method. Additionally to the header fields, the API now requires a JSON data field with the desired values for the new DNS record - from the example above:

{
"type": "TXT",
"name": "_acme-challenge.www",
"content": "acbdefghijklmnopqrstuvwxyz",
"ttl": 20
}

Notice about TXT-, CAA- und TLSA-Records

Since TXT, CAA and TLSA fields can exist multiple times with different content if they have the same name, the "content" parameter may be an array!

Example 1: "content": ["zeile1", "zeile2", "zeile3"]
Example 2: --data '{
    "name": "_25._tcp.example",
    "ttl": 120,
    "type": "TLSA",
    "content": [
    "3 1 1 654321",
    "3 1 1 123456"
    ]
}'
Example 3: --data '{
    "name": "",
    "ttl": 120,
    "type": "CAA",
    "content": [
    "0 issue \"symantec.com\"",
    "0 issue \"letsencrypt.org\""
    ]
}'

The third parameter of the CAA record should be bracketed like with \"letsencrypt.org\".

The parameters "type ", "name " and "content " are mandatory. The "ttl " time specification is given in seconds. This is 120 (i.e. 2 minutes) by default, but can be optionally specified as a value between 0 and 604800 (1 week).

To set a content for the main domain (example: example.org) we leave the Name field empty: "name": "".

Attention

If a DNS entry already exists with that name, it will be overwritten.

Example: Removing a record in a domain via cURL

curl -X DELETE 'https://api.servercow.de/dns/v1/domains/example.org' \
-H 'X-Auth-Username: servercow_username' \
-H 'X-Auth-Password: servercow_password' \
-H 'Content-Type: application/json' \
--data '{"type":"TXT","name":"_acme-challenge.www"}'

In the above request we use the DELETE method. In addition to the header fields, the API requires a JSON data field with the mandatory "type " and "name " to remove the corresponding entry:

{
    "type": "TXT",
    "name": "_acme-challenge.www"
}