API docs by Redocly

DNSY REST API (0.1.1)

Download OpenAPI specification:

License: Apache-2.0

Management API of the DNSY DNS server. Errors are RFC 9457 problem+json.

acl

get_acl

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "default_action": "allow",
  • "rate_limit_qps": 0,
  • "rules": [
    ]
}

create_rule

Authorizations:
bearersession
Request Body schema: application/json
required
action
required
string (Action)
Enum: "allow" "refuse" "drop"

What to do with a matching client.

cidr
string or null

Address or network, e.g. 203.0.113.7 or 10.0.0.0/8 (longest prefix wins).

client_cert_sha256
string or null

SHA-256 fingerprint (64 hex digits) of an mTLS client certificate.

comment
string

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "cidr": "string",
  • "client_cert_sha256": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "action": "allow",
  • "cidr": "string",
  • "client_cert_sha256": "string",
  • "comment": "string",
  • "id": 0
}

set_rate_limit

Authorizations:
bearersession
Request Body schema: application/json
required
qps
required
integer <int32> >= 0

Queries per second per client; 0 disables limiting. At most 1,000,000.

Responses

Request samples

Content type
application/json
{
  • "qps": 0
}

Response samples

Content type
application/json
{
  • "qps": 0
}

delete_rule

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Rule id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

get_response_ip

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "cidrs": [
    ]
}

put_response_ip

Authorizations:
bearersession
Request Body schema: application/json
required
cidrs
required
Array of strings

Addresses or networks, e.g. 10.0.0.0/8 or 192.0.2.1. An upstream answer with an A or AAAA record inside any of them is blocked (EDE 15). An empty list disables the policy.

Responses

Request samples

Content type
application/json
{
  • "cidrs": [
    ]
}

Response samples

Content type
application/json
{
  • "cidrs": [
    ]
}

auth

Create the first admin with the one-time code printed at startup.

Request Body schema: application/json
required
code
required
string

The one-time code printed to stderr at startup.

password
required
string

At least 8 characters.

username
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

Log in with username and password; sets the session and CSRF cookies.

Request Body schema: application/json
required
password
required
string
username
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

End the current session and clear the cookies.

Authorizations:
session

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

The authenticated caller.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string",
  • "auth": "string"
}

Change the caller's password. Ends all sessions and starts a new one for this client. The current password is checked as a login (same throttle, 429 when locked out).

Authorizations:
session
Request Body schema: application/json
required
current_password
required
string
new_password
required
string

At least 8 characters.

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

blocklists

list_blocklists

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create_blocklist

Authorizations:
bearersession
Request Body schema: application/json
required
allow_private
boolean

Allow private, loopback and link-local targets. Needs the admin scope.

enabled
boolean or null

Default true.

Format (string) or null
interval_secs
integer or null <int64> >= 0

Seconds between refreshes, 60 to 2,592,000; default 86,400.

location
required
string

http:// or https:// URL, or a file path (file paths need the admin scope).

name
required
string

Unique, 1 to 128 characters.

Responses

Request samples

Content type
application/json
{
  • "allow_private": true,
  • "enabled": true,
  • "format": "auto",
  • "interval_secs": 0,
  • "location": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "allow_private": true,
  • "enabled": true,
  • "entries": 0,
  • "format": "auto",
  • "id": 0,
  • "interval_secs": 0,
  • "last_fetched": 0,
  • "last_status": "string",
  • "location": "string",
  • "name": "string"
}

delete_blocklist

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Source id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

patch_blocklist

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Source id

Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "allow_private": true,
  • "enabled": true,
  • "entries": 0,
  • "format": "auto",
  • "id": 0,
  • "interval_secs": 0,
  • "last_fetched": 0,
  • "last_status": "string",
  • "location": "string",
  • "name": "string"
}

refresh_blocklist

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Source id

Responses

Response samples

Content type
application/json
{
  • "entries": 0,
  • "outcome": "string"
}

cache

Live cache statistics.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "capacity": 0,
  • "entries": 0,
  • "evictions": 0,
  • "expired": 0,
  • "hit_ratio": 0.1,
  • "hits": 0,
  • "inserts": 0,
  • "misses": 0,
  • "prefetches": 0,
  • "stale_served": 0
}

Remove every cache entry. Needs `api:write`.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "removed": 0
}

Remove the entries of one name, optionally with its subtree. Needs `api:write`.

Authorizations:
bearersession
query Parameters
name
required
string

Domain name whose entries are removed.

subtree
boolean

Also remove everything below the name (default false).

Responses

Response samples

Content type
application/json
{
  • "removed": 0
}

client-certs

list_certs

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create_cert

Authorizations:
bearersession
Request Body schema: application/json
required
expires_at
integer or null <int64>

Unix seconds in the future; omit for no expiry.

label
required
string

1 to 128 characters.

sha256
required
string

SHA-256 fingerprint: 64 hex digits, optionally colon separated.

Responses

Request samples

Content type
application/json
{
  • "expires_at": 0,
  • "label": "string",
  • "sha256": "string"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "enabled": true,
  • "expired": true,
  • "expires_at": 0,
  • "id": 0,
  • "label": "string",
  • "sha256": "string"
}

delete_cert

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Certificate id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

patch_cert

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Certificate id

Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "enabled": true,
  • "expired": true,
  • "expires_at": 0,
  • "id": 0,
  • "label": "string",
  • "sha256": "string"
}

dnssec

Export the zone keys as a bundle encrypted under the given passphrase, for backup. The response holds ciphertext only; the passphrase and the keys are never logged. Refused with 403 when the API listener is plain HTTP.

Authorizations:
bearersession
Request Body schema: application/json
required
passphrase
required
string

Passphrase the bundle is encrypted under (at least 12 characters). It may differ from the key passphrase; keep it apart from the bundle. Wiped from memory on drop.

zone
string or null

Export only this zone's keys; omitted exports every zone's.

Responses

Request samples

Content type
application/json
{
  • "passphrase": "string",
  • "zone": "string"
}

Response samples

Content type
application/json
{
  • "bundle": "string"
}

Change the key passphrase: every stored private key is re-encrypted under the new one in a single transaction (all or none). Keys stored unencrypted become encrypted. The running server uses the new passphrase at once; update `DNSY_DNSSEC_PASSPHRASE` or the passphrase file before the next start, or the keys cannot be read.

Authorizations:
bearersession
Request Body schema: application/json
required
new_passphrase
required
string

The new key passphrase (at least 12 characters). Wiped from memory on drop.

Responses

Request samples

Content type
application/json
{
  • "new_passphrase": "string"
}

Response samples

Content type
application/json
{
  • "keys_reencrypted": 0
}

Validation counters of the last 24 hours and whether the clock is trusted.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "bogus": 0,
  • "clock_trusted": true,
  • "counters": {
    },
  • "secure": 0,
  • "signed_zones": 0,
  • "validation": "off",
  • "window_ms": 0
}

Validation mode, negative trust anchors and the (read-only) trust anchors.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "negative_trust_anchor_entries": [
    ],
  • "negative_trust_anchors": [
    ],
  • "trust_anchors": [
    ],
  • "validation": "off"
}

Change the validation mode or the negative trust anchors at run time. A change flushes the resolver cache.

Authorizations:
bearersession
Request Body schema: application/json
required
Array of strings or NtaEntryInput (object) or null (NtaInput)

Replaces the whole list; [] clears it. An entry is a name, or {name, expires_at} for an anchor that stops applying at expires_at (Unix time).

ValidationMode (string) or null

Responses

Request samples

Content type
application/json
{
  • "negative_trust_anchors": [
    ],
  • "validation": "off"
}

Response samples

Content type
application/json
{
  • "negative_trust_anchor_entries": [
    ],
  • "negative_trust_anchors": [
    ],
  • "trust_anchors": [
    ],
  • "validation": "off"
}

A zone's DNSSEC policy, keys and rollover state.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Responses

Response samples

Content type
application/json
{
  • "algorithm": 0,
  • "denial": "nsec",
  • "dnskey_ttl": 0,
  • "enabled": true,
  • "key_layout": "csk",
  • "keys": [
    ],
  • "keys_encrypted": true,
  • "next_resign": 0,
  • "nsec3": {
    },
  • "propagation_delay": 0,
  • "refresh_days": 0,
  • "rollover": {
    },
  • "signature_validity_days": 0
}

Enable, disable or change a zone's signing policy. Writes the zone file's `dnssec` block; enabling creates the keys and signs the zone before the response is sent.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Request Body schema: application/json
required
algorithm
integer or null <int32> >= 0

13 (ECDSAP256SHA256) or 15 (Ed25519). Existing keys are replaced only by a rollover.

DenialBody (string) or null
dnskey_ttl
integer or null <int32> >= 0
enabled
required
boolean

Sign the zone. Turning it on creates the zone's keys.

KeyLayoutBody (string) or null
Nsec3Body (object) or null
propagation_delay
integer or null <int32> >= 0

Seconds added to the DNSKEY TTL before a published key may sign (default 3600, at most 604800).

refresh_days
integer or null <int32> >= 0
signature_validity_days
integer or null <int32> >= 0

Responses

Request samples

Content type
application/json
{
  • "algorithm": 0,
  • "denial": "nsec",
  • "dnskey_ttl": 0,
  • "enabled": true,
  • "key_layout": "csk",
  • "nsec3": {
    },
  • "propagation_delay": 0,
  • "refresh_days": 0,
  • "signature_validity_days": 0
}

Response samples

Content type
application/json
{
  • "algorithm": 0,
  • "denial": "nsec",
  • "dnskey_ttl": 0,
  • "enabled": true,
  • "key_layout": "csk",
  • "keys": [
    ],
  • "keys_encrypted": true,
  • "next_resign": 0,
  • "nsec3": {
    },
  • "propagation_delay": 0,
  • "refresh_days": 0,
  • "rollover": {
    },
  • "signature_validity_days": 0
}

DS records (SHA-256 and SHA-384) and DNSKEY records of the zone's KSKs and CSKs, for the parent zone or registrar. JSON by default; `Accept: text/plain` returns zone-file lines.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Responses

Response samples

Content type
application/json
{
  • "dnskey": [
    ],
  • "ds": [
    ],
  • "zone": "string"
}

The zone's keys (public metadata only), including removed ones.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate a key in the `generated` state (not yet published). The zone needs signing enabled.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Request Body schema: application/json
required
algorithm
integer or null <int32> >= 0

13 or 15; defaults to the zone policy's algorithm.

role
required
string (KeyRoleBody)
Enum: "csk" "ksk" "zsk"

csk, ksk or zsk.

Responses

Request samples

Content type
application/json
{
  • "algorithm": 0,
  • "role": "csk"
}

Response samples

Content type
application/json
{
  • "active_at": 0,
  • "algorithm": 0,
  • "created_at": 0,
  • "ds_confirmed_at": 0,
  • "id": 0,
  • "key_tag": 0,
  • "published_at": 0,
  • "removed_at": 0,
  • "retired_at": 0,
  • "role": "string",
  • "state": "string"
}

Record that the key's DS is published at the parent; a KSK or CSK rollover waits for this.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

id
required
integer <int64>

Published KSK or CSK

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

Start a rollover of the role of an active key: a new key is generated and published, and the rollover state machine moves it along. KSK and CSK rollovers wait for `ds-confirmed`.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

id
required
integer <int64>

Active key to replace

Request Body schema: application/json
required

Optional

algorithm
integer or null <int32> >= 0

Algorithm of the new key (13 or 15); defaults to the rolled key's algorithm.

Responses

Request samples

Content type
application/json
{
  • "algorithm": 0
}

Response samples

Content type
application/json
{
  • "active_at": 0,
  • "algorithm": 0,
  • "created_at": 0,
  • "ds_confirmed_at": 0,
  • "id": 0,
  • "key_tag": 0,
  • "published_at": 0,
  • "removed_at": 0,
  • "retired_at": 0,
  • "role": "string",
  • "state": "string"
}

Abort the rollover of one role (or of every role): the incoming key is withdrawn and its private key destroyed, and the active key keeps signing. A rollover whose new key already became active cannot be aborted. If the incoming KSK or CSK's DS was already published at the parent, remove it there.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Request Body schema: application/json
required

Optional

KeyRoleBody (string) or null

Responses

Request samples

Content type
application/json
{
  • "role": "csk"
}

Response samples

Content type
application/json
{
  • "algorithm": 0,
  • "denial": "nsec",
  • "dnskey_ttl": 0,
  • "enabled": true,
  • "key_layout": "csk",
  • "keys": [
    ],
  • "keys_encrypted": true,
  • "next_resign": 0,
  • "nsec3": {
    },
  • "propagation_delay": 0,
  • "refresh_days": 0,
  • "rollover": {
    },
  • "signature_validity_days": 0
}

querylog

Search the query log, newest first.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds.

to
integer <int64>

Exclusive end, unix milliseconds.

client
string

Exact client address (the network address when client redaction is on).

domain
string

Case-insensitive substring of the query name.

type
string

Query type by name (A, AAAA, ...) or number.

outcome
string

Response code by name (NOERROR, NXDOMAIN, ...) or number.

source
string

authoritative, cache, cache_stale, upstream, blocked, refused or error.

dnssec
string

unchecked, secure, insecure, bogus or indeterminate.

limit
integer >= 0

Page size, 1 to 500 (default 100).

cursor
string

next_cursor of the previous page.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "next_cursor": "string"
}

Live tail of the query log as server-sent events.

Events are named query and carry one log record as JSON; lagged means rows were skipped because the consumer was too slow. The server polls at its own pace, so a slow consumer never makes it buffer. The number of concurrent streams is capped (429 beyond). Takes the same filters as the search (from/to bound the stream). Needs api:write (operator or admin).

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds.

to
integer <int64>

Exclusive end, unix milliseconds.

client
string

Exact client address (the network address when client redaction is on).

domain
string

Case-insensitive substring of the query name.

type
string

Query type by name (A, AAAA, ...) or number.

outcome
string

Response code by name (NOERROR, NXDOMAIN, ...) or number.

source
string

authoritative, cache, cache_stale, upstream, blocked, refused or error.

dnssec
string

unchecked, secure, insecure, bogus or indeterminate.

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

rules

list_rules

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create_rule

Authorizations:
bearersession
Request Body schema: application/json
required
domain
required
string

Domain name, e.g. ads.example.com; subdomains match too.

kind
required
string (RuleKindView)
Enum: "block" "allow"

Custom rule kind.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "kind": "block"
}

Response samples

Content type
application/json
{
  • "domain": "string",
  • "id": 0,
  • "kind": "block"
}

delete_rule

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Rule id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

settings

get_settings

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
{
  • "cache": {
    },
  • "filter": {
    },
  • "limits": {
    },
  • "querylog": {
    }
}

patch_settings

Authorizations:
bearersession
Request Body schema: application/json
required
CachePatch (object) or null
FilterPatch (object) or null
LimitsPatch (object) or null
QueryLogPatch (object) or null

Responses

Request samples

Content type
application/json
{
  • "cache": {
    },
  • "filter": {
    },
  • "limits": {
    },
  • "querylog": {
    }
}

Response samples

Content type
application/json
{
  • "cache": {
    },
  • "filter": {
    },
  • "limits": {
    },
  • "querylog": {
    }
}

stats

Summary, timeseries and the three top lists for one range: the same data as the individual `/stats/*` routes, with the same parameters, limits and read scope.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

bucket
integer <int64> >= 0

Timeseries bucket width in seconds, a multiple of 60 (default 3600).

limit
integer >= 0

Entries per top list, 1 to 100 (default 10).

Responses

Response samples

Content type
application/json
{
  • "series": [
    ],
  • "summary": {
    },
  • "top_blocked": [
    ],
  • "top_clients": [
    ],
  • "top_domains": [
    ]
}

Totals, answer sources, DNSSEC status counts, cache hit ratio, blocked ratio and latency.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

Responses

Response samples

Content type
application/json
{
  • "avg_latency_us": 0,
  • "blocked": 0,
  • "blocked_ratio": 0.1,
  • "by_rcode": {
    },
  • "by_source": {
    },
  • "cache_hit_ratio": 0.1,
  • "cache_hits": 0,
  • "cache_misses": 0,
  • "dnssec": {
    },
  • "from": 0,
  • "max_latency_us": 0,
  • "querylog_dropped": 0,
  • "querylog_flush_errors": 0,
  • "stale_answers": 0,
  • "to": 0,
  • "total": 0
}

Query counts per bucket (only buckets with data), oldest first.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

bucket
integer <int64> >= 0

Bucket width in seconds, a multiple of 60 (default 3600).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Most blocked names.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

limit
integer >= 0

Number of entries, 1 to 100 (default 10).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Busiest clients (network addresses when client redaction is on).

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

limit
integer >= 0

Number of entries, 1 to 100 (default 10).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Most queried names.

Authorizations:
bearersession
query Parameters
from
integer <int64>

Inclusive start, unix milliseconds (default: to minus 24 hours).

to
integer <int64>

Exclusive end, unix milliseconds (default: now).

limit
integer >= 0

Number of entries, 1 to 100 (default 10).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

tokens

List the caller's tokens; admins see everyone's.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a token for the caller. Needs a session, so a token cannot mint tokens.

Authorizations:
session
Request Body schema: application/json
required
expires_at
integer or null <int64>

Unix seconds; omit for a token that does not expire.

name
required
string
scopes
required
Array of strings

Must be allowed by the caller's role.

Responses

Request samples

Content type
application/json
{
  • "expires_at": 0,
  • "name": "string",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "token": "string"
}

Revoke a token (own tokens; admins any).

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

Token id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

upstreams

list_groups

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create_group

Authorizations:
bearersession
Request Body schema: application/json
required
default
boolean

Receives queries no domain pattern matches. Exactly one group is the default.

domains
Array of strings

Patterns such as corp.example or *.corp.example.

required
Array of objects (MemberInput)
strategy
required
string (StrategyView)
Enum: "round_robin" "weighted" "lowest_latency" "failover"

How a group orders its members.

name
required
string

1 to 64 characters of [A-Za-z0-9._-].

Responses

Request samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "members": [
    ],
  • "strategy": "round_robin",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "health": [
    ],
  • "members": [
    ],
  • "name": "string",
  • "strategy": "round_robin"
}

get_group

Authorizations:
bearersession
path Parameters
name
required
string

Group name

Responses

Response samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "health": [
    ],
  • "members": [
    ],
  • "name": "string",
  • "strategy": "round_robin"
}

replace_group

Authorizations:
bearersession
path Parameters
name
required
string

Group name

Request Body schema: application/json
required
default
boolean

Receives queries no domain pattern matches. Exactly one group is the default.

domains
Array of strings

Patterns such as corp.example or *.corp.example.

required
Array of objects (MemberInput)
strategy
required
string (StrategyView)
Enum: "round_robin" "weighted" "lowest_latency" "failover"

How a group orders its members.

Responses

Request samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "members": [
    ],
  • "strategy": "round_robin"
}

Response samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "health": [
    ],
  • "members": [
    ],
  • "name": "string",
  • "strategy": "round_robin"
}

delete_group

Authorizations:
bearersession
path Parameters
name
required
string

Group name

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

group_health

Authorizations:
bearersession
path Parameters
name
required
string

Group name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

add_member

Authorizations:
bearersession
path Parameters
name
required
string

Group name

Request Body schema: application/json
required
upstream
required
string

udp://host[:port], tcp://host[:port] or tls://host[:port][#sni].

weight
integer or null <int32> >= 0

Used by the weighted strategy; 1 to 1000, default 1.

Responses

Request samples

Content type
application/json
{
  • "upstream": "string",
  • "weight": 0
}

Response samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "health": [
    ],
  • "members": [
    ],
  • "name": "string",
  • "strategy": "round_robin"
}

remove_member

Authorizations:
bearersession
path Parameters
name
required
string

Group name

index
required
integer >= 0

Member index as listed

Responses

Response samples

Content type
application/json
{
  • "default": true,
  • "domains": [
    ],
  • "health": [
    ],
  • "members": [
    ],
  • "name": "string",
  • "strategy": "round_robin"
}

users

List all users.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user.

Authorizations:
bearersession
Request Body schema: application/json
required
password
required
string

At least 8 characters.

role
required
string
username
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "role": "viewer",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

Get one user.

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

User id

Responses

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

Delete a user. Their tokens and sessions go with them. The last active admin cannot be deleted.

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

User id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

Change a user's role, reset the password, and/or disable or enable the user.

Authorizations:
bearersession
path Parameters
id
required
integer <int64>

User id

Request Body schema: application/json
required
disabled
boolean or null

true disables the user (sessions end at once, tokens are refused, login fails); false enables them again. The last active admin cannot be disabled.

password
string or null

Reset the password (at least 8 characters); ends all of the user's sessions.

role
string or null

Changing the role ends all of the user's sessions.

Responses

Request samples

Content type
application/json
{
  • "disabled": true,
  • "password": "string",
  • "role": "operator"
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "disabled": true,
  • "disabled_at": 0,
  • "id": 0,
  • "role": "viewer",
  • "username": "string"
}

meta

The server version.

Responses

Response samples

Content type
application/json
{
  • "version": "string"
}

The process is up.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

The process can serve requests (the database answers).

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "warnings": [
    ]
}

zones

List zones.

Authorizations:
bearersession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a zone.

Authorizations:
bearersession
Request Body schema: application/json
required
default_ttl
required
integer <int32> >= 0
name
required
string

Zone name, e.g. example.com..

Array of objects (RecordInput)

Must contain at least one NS record at the apex.

required
object (SoaBody)

The SOA record of a zone.

Responses

Request samples

Content type
application/json
{
  • "default_ttl": 0,
  • "name": "string",
  • "records": [
    ],
  • "soa": {
    }
}

Response samples

Content type
application/json
{
  • "default_ttl": 0,
  • "dnssec_enabled": true,
  • "load_error": "string",
  • "name": "string",
  • "record_count": 0,
  • "soa": {
    }
}

Get a zone, with its `load_error` and an `ETag`.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Responses

Response samples

Content type
application/json
{
  • "default_ttl": 0,
  • "dnssec_enabled": true,
  • "load_error": "string",
  • "name": "string",
  • "record_count": 0,
  • "soa": {
    }
}

Replace a zone's settings and records. The DNSSEC policy is kept; the serial is bumped.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Request Body schema: application/json
required
default_ttl
required
integer <int32> >= 0
Array of objects (RecordInput)

Must contain at least one NS record at the apex.

required
object (SoaBody)

The SOA record of a zone.

Responses

Request samples

Content type
application/json
{
  • "default_ttl": 0,
  • "records": [
    ],
  • "soa": {
    }
}

Response samples

Content type
application/json
{
  • "default_ttl": 0,
  • "dnssec_enabled": true,
  • "load_error": "string",
  • "name": "string",
  • "record_count": 0,
  • "soa": {
    }
}

Delete a zone and its file.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

Download the zone as a BIND master file, unsigned or (`signed=true`) with its DNSSEC records.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

query Parameters
signed
boolean

Export the signed zone: adds DNSKEY, RRSIG, NSEC or NSEC3 and NSEC3PARAM records.

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

List records of a zone (paged). The SOA is part of the zone detail, not listed here.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

limit
required
integer or null >= 0

Page size (default 100, at most 1000).

offset
required
integer or null >= 0
type
required
string or null

Only this record type.

name
required
string or null

Only this owner name (relative or absolute).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Add a record. The SOA serial is bumped.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

Request Body schema: application/json
required
name
required
string

@, a name relative to the zone, or an absolute name ending in a dot.

ttl
integer or null <int32> >= 0

Seconds; defaults to the zone default TTL.

type
required
string

A, AAAA, NS, CNAME, PTR, MX, TXT, SRV or CAA.

value
required
string

Presentation-format rdata, e.g. 10 mail.example.com..

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ttl": 0,
  • "type": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "ttl": 0,
  • "type": "string",
  • "value": "string"
}

Replace a record. The id changes when name, type or value change. The serial is bumped.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

id
required
string

Record id

Request Body schema: application/json
required
name
required
string

@, a name relative to the zone, or an absolute name ending in a dot.

ttl
integer or null <int32> >= 0

Seconds; defaults to the zone default TTL.

type
required
string

A, AAAA, NS, CNAME, PTR, MX, TXT, SRV or CAA.

value
required
string

Presentation-format rdata, e.g. 10 mail.example.com..

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ttl": 0,
  • "type": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "ttl": 0,
  • "type": "string",
  • "value": "string"
}

Delete a record. The apex keeps at least one NS record. The serial is bumped.

Authorizations:
bearersession
path Parameters
name
required
string

Zone name

id
required
string

Record id

Responses

Response samples

Content type
application/problem+json
{
  • "detail": "string",
  • "retry_after_secs": 0,
  • "status": 0,
  • "title": "string",
  • "type": "string"
}