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

The API supports the following types: A, AAAA, CNAME, TXT, MX, CAA, TLSA, SRV, SSHFP, SMIMEA, HTTPS and SVCB.

---

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, TLSA, HTTPS and SVCB records

Since TXT, CAA, TLSA, HTTPS and SVCB 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\".

Notice about HTTPS and SVCB records

HTTPS and SVCB records (RFC 9460) use the format priority target [key=value ...]. They are needed e.g. to announce HTTP/3 or to use Encrypted Client Hello (ECH).

{
  "type": "HTTPS",
  "name": "www",
  "content": "1 . alpn=h2,h3 ech=AEn+DQBF...",
  "ttl": 300
}

• Priority: 1 to 65535 for regular entries. 0 is alias mode and only points to another hostname, e.g. 0 svc.example.net (no parameters).
• Target: . stands for the record's own name, otherwise another hostname.
• Parameters: alpn, no-default-alpn, port, ipv4hint, ipv6hint, ech, mandatory as well as key7 to key65534.
• Port-specific names such as _8443._https.www are supported.

The API normalizes the content when saving (parameters sorted by key, ech in quotes). When reading you will get e.g. 1 . alpn=h2,h3 ech="AEn+DQBF...". You can send this value back to the API unchanged.

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