API docs by Redocly

Bindizr HTTP API (0.1.0-rc.2)

Download OpenAPI specification:

E-mail: kevin136583@gmail.com License: Apache 2.0

This is the API documentation for Bindizr

Health

Service health probe for load balancers and orchestrators.

Health probe

Runs a minimal database query and reports whether the API can serve requests. Unauthenticated, intended for load-balancer and orchestrator probes; deeper checks (DNS listener, secondary sync) belong to 'bindizr doctor'.

Authorizations:
None

Responses

Response samples

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

Zone

Manage DNS zones including creation, update, deletion, and retrieval.

List all DNS zones

Authorizations:
bearer_auth
query Parameters
name
string

Filter by zone name.

id
integer <int32>

Filter by zone ID.

mname
string

Filter by mname.

rname
string

Filter by rname.

default_ttl
integer <int32>

Filter by default TTL.

min_default_ttl
integer <int32>

Filter by minimum default TTL.

max_default_ttl
integer <int32>

Filter by maximum default TTL.

serial
integer <int32> >= 0

Filter by serial.

min_serial
integer <int32> >= 0

Filter by minimum serial.

max_serial
integer <int32> >= 0

Filter by maximum serial.

created_after
string <date-time>

Keep zones created at or after this RFC 3339 timestamp.

created_before
string <date-time>

Keep zones created at or before this RFC 3339 timestamp.

signed
boolean

true keeps the zones signing under a DNSSEC policy, false the rest.

enabled
boolean

true keeps the zones the DNS plane serves, false the disabled ones.

search
string

Partially search zones.

sort
string

name (the default), serial, default_ttl, or created_at.

order
string

asc (the default) or desc.

limit
integer <int32> [ 1 .. 1000 ]

Zones per page; defaults to 50 when omitted, 1000 is the largest page accepted.

offset
integer <int64> >= 0

Number of zones to skip.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create a new DNS zone

Authorizations:
bearer_auth
Request Body schema: application/json
required
apex_ns
boolean
Default: true

Start the zone with an apex NS record naming the SOA MNAME; false leaves every NS record to the caller.

default_ttl
integer or null <int32>

Record TTL the zone hands out when a record names none; defaults to dns.zone_defaults.ttl.

description
string or null

Free-text note for operators, at most 255 characters.

dry_run
boolean

Validate and report the change without writing it.

expire
integer or null <int32>
minimum_ttl
integer or null <int32>
mname
required
string
name
required
string
refresh
integer or null <int32>
retry
integer or null <int32>
rname
required
string
serial
integer or null <int32> >= 0

Starting serial, auto-generated if not provided. Must be 1-2137483647 so the counter keeps room to advance, and can only be set at creation.

Responses

Request samples

Content type
application/json
{
  • "apex_ns": true,
  • "default_ttl": 3600,
  • "description": "customer A, migrated 2026-01",
  • "dry_run": false,
  • "expire": 604800,
  • "minimum_ttl": 3600,
  • "mname": "ns1.example.com",
  • "name": "example.com",
  • "refresh": 7200,
  • "retry": 3600,
  • "rname": "admin@example.com",
  • "serial": 42
}

Response samples

Content type
application/json
{
  • "applied": true,
  • "dry_run": false,
  • "zone": {
    }
}

Get a specific DNS zone

Returns the zone's SOA metadata. For its records, list them with GET /records?zone_name=, or render the whole zone as a master file with GET /zones/{name}/export.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to retrieve.

Responses

Response samples

Content type
application/json
{
  • "zone": {
    }
}

Update a specific DNS zone

Applies the given fields and keeps the rest; a different name renames the zone, which also needs zone:create in all zones. The serial advances by itself and cannot be set here.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to update.

Request Body schema: application/json
required
default_ttl
integer or null <int32>
description
string or null

Empty clears the note.

dry_run
boolean

Validate and report the change without writing it.

enabled
boolean or null

false stops the DNS plane serving the zone without deleting it.

expire
integer or null <int32>
minimum_ttl
integer or null <int32>
mname
string or null
name
string or null

A different name renames the zone.

refresh
integer or null <int32>
retry
integer or null <int32>
rname
string or null
serial
integer or null <int32> >= 0

Responses

Request samples

Content type
application/json
{
  • "default_ttl": 3600,
  • "description": "customer A, migrated 2026-01",
  • "dry_run": false,
  • "enabled": true,
  • "expire": 604800,
  • "minimum_ttl": 3600,
  • "mname": "ns1.example.com",
  • "name": "example.com",
  • "refresh": 7200,
  • "retry": 3600,
  • "rname": "admin@example.com",
  • "serial": 42
}

Response samples

Content type
application/json
{
  • "applied": true,
  • "dry_run": false,
  • "zone": {
    }
}

Delete a specific DNS zone

Deletes the zone with its records and saved versions, and answers with what went. With dry_run=true the counts are reported and nothing is removed.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to delete.

query Parameters
dry_run
boolean

Report what the request would do without applying it.

Responses

Response samples

Content type
application/json
{
  • "applied": true,
  • "dry_run": false,
  • "records_deleted": 1240,
  • "versions_deleted": 12,
  • "zone": {
    }
}

Export a zone as BIND master-file text

Renders the zone and its records as an RFC 1035 master file, the inverse of the import endpoint. With signed, the derived DNSSEC records (DNSKEY, RRSIG, the denial chain, CDS/CDNSKEY) are appended in presentation form — an inspection artifact, not an import input.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to export.

query Parameters
signed
boolean

Append the derived DNSSEC records.

Responses

Response samples

Content type
application/json
{
  • "code": "INVALID_INPUT",
  • "error": "zone with name 'example.com' not found"
}

Import records into a zone

Reconcile records with the zone using append/upsert/replace, taken from BIND zone file text in content or transferred over AXFR from from_server (exactly one of the two; the source must allow the transfer). When applied, the zone serial is incremented once and a single NOTIFY is sent. If any record fails validation nothing is applied and the answer is 422, carrying the per-record errors. A record type bindizr does not store fails the file the same way unless skip_unsupported is set, which passes over those records and lists them in skipped_records. TTLs are decimal seconds as RFC 1035 defines them; a file using BIND's unit suffixes (1h) is refused — write it out in seconds first with named-compilezone -o - <zone> <file>.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to import records into.

Request Body schema: application/json
required
content
string or null

Raw BIND zone file text.

create
boolean

Create the zone from the file's SOA when it does not exist yet, which needs zone:create and the mode's record actions in all zones. Its initial serial must be 1..=2137483647; an unsupported serial rejects both a dry run and an apply without creating the zone. Applying record changes advances the serial once. Without this a missing zone is an error, so a typo creates nothing.

dry_run
boolean

When true, parse and validate without applying any change.

from_server
string or null

Transfer source (host[:port], port 53 default) to pull the zone from over AXFR; its SOA seeds a missing zone when create is true. SOA and DNSSEC-derived records are not imported as ordinary records.

mode
string (ImportMode)
Default: "append"
Enum: "append" "upsert" "replace"

Reconciliation mode: append (default), upsert, or replace.

skip_unsupported
boolean

Pass over records bindizr has no type for instead of failing the whole file; they are counted as skipped and listed in skipped_records.

Responses

Request samples

Content type
application/json
{
  • "content": "www IN A 192.0.2.1\nmail IN A 192.0.2.2\n",
  • "create": true,
  • "dry_run": true,
  • "from_server": "192.0.2.1:53",
  • "mode": "append",
  • "skip_unsupported": true
}

Response samples

Content type
application/json
{
  • "applied": true,
  • "diff": {
    },
  • "dry_run": false,
  • "errors": [
    ],
  • "skipped_records": [
    ],
  • "summary": {
    }
}

Check how far each secondary has caught up with a zone

Queries every enabled secondary for the SOA serial it currently serves and compares it with the zone's serial. Probes run live and in parallel; an unreachable secondary is reported with the failure reason. With no enabled secondaries the list is empty.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "secondaries": [
    ],
  • "serial": 42,
  • "zone_name": "example.com"
}

List a zone's versions (serial history)

Every zone mutation records a version of the zone's SOA metadata keyed by serial. Versions are returned newest serial first.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

Versions per page; defaults to 50.

offset
integer <int64> >= 0

Number of versions to skip.

include_signer_serials
boolean

Include past serials with only derived DNSSEC changes. By default these are hidden; the current serial and serials without journal entries remain visible.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Diff the records between two of a zone's serials

Reports the records added, removed, and changed between from and to, grouped by name and type. Omitting to compares against the current serial. Each serial must be the current one or an existing version.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

query Parameters
from
required
integer <int32> >= 0

The serial to diff from.

to
integer <int32> >= 0

The serial to diff to; defaults to the current serial.

Responses

Response samples

Content type
application/json
{
  • "diff": {
    },
  • "from_serial": 41,
  • "to_serial": 42
}

Get the zone state captured at a version serial

Returns the version's SOA fields together with the zone's records at that serial, reconstructed from the journal.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

serial
required
integer <int32> >= 0

The version serial to inspect.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ],
  • "version": {
    }
}

Roll a zone back to a version serial

Restores the zone's records and SOA metadata to the state captured at the target serial. The zone serial still advances to a new value (serials never go backward) and a single NOTIFY is sent. The zone name is not part of a version and is never changed. It needs zone:update, and record:read, record:create and record:delete with no name or type narrowing, since it reads the version it restores. With dry_run=true the rollback is computed and reported without applying any change.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to roll back.

serial
required
integer <int32> >= 0

The version serial to roll back to.

query Parameters
dry_run
boolean

Report what the request would do without applying it.

Responses

Response samples

Content type
application/json
{
  • "applied": true,
  • "dry_run": false,
  • "new_serial": 13,
  • "summary": {
    },
  • "target_serial": 7
}

Record

Manage DNS records including creation, update, deletion, and retrieval.

List all DNS records

Authorizations:
bearer_auth
query Parameters
zone_name
string

The name of the DNS zone to filter records by.

name
string

Filter by record name.

type
string

Filter by record type.

value
string

Partially filter by record value.

ttl
integer <int32>

Filter by TTL.

min_ttl
integer <int32>

Filter by minimum TTL.

max_ttl
integer <int32>

Filter by maximum TTL.

priority
integer <int32>

Filter by priority.

min_priority
integer <int32>

Filter by minimum priority.

max_priority
integer <int32>

Filter by maximum priority.

search
string

Partially search records.

sort
string

name (the default), type, ttl, priority, or created_at.

order
string

asc (the default) or desc.

signed
boolean

Append the zone's derived DNSSEC records (RRSIG, DNSKEY, NSEC/NSEC3/NSEC3PARAM, CDS, CDNSKEY) after the user records, in the same pagination. Derived rows carry no id, and type also accepts a derived type. A search narrows them by name only, a priority filter leaves them out, and a value filter is refused rather than answered without them.

limit
integer <int32> [ 1 .. 1000 ]

Records per page; defaults to 50 when omitted, 1000 is the largest page accepted.

offset
integer <int64> >= 0

Number of records to skip.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create a new DNS record

Authorizations:
bearer_auth
Request Body schema: application/json
required
dry_run
boolean

Validate and report the change without writing it.

name
required
string
priority
integer or null <int32>

MX and SRV priority, set here rather than inline in the value; other record types reject it. Omitted, it is served and compared as 10.

ttl
integer or null <int32>

Optional; an omitted TTL is fixed to the zone's TTL at write time. Records sharing a name and type share one TTL.

type
required
string
required
string or Array of strings (RecordValue)
zone_name
required
string

Responses

Request samples

Content type
application/json
{
  • "dry_run": false,
  • "name": "sub",
  • "priority": 10,
  • "ttl": 3600,
  • "type": "A",
  • "value": "192.168.1.100",
  • "zone_name": "example.com"
}

Response samples

Content type
application/json
{
  • "applied": true,
  • "diff": {
    },
  • "dry_run": false,
  • "record": {
    }
}

Delete records by name

Removes every record matching the filter in one transaction, so the zone advances by a single serial and sends one NOTIFY. Narrowing follows RFC 2136, Section 2.5.2: a name alone takes every type at it, adding type narrows to that type, adding value takes one record. Matching nothing is not an error — the zone already reads the way the request asked for, so nothing moves.

Authorizations:
bearer_auth
query Parameters
zone_name
required
string
name
required
string

Owner name relative to the zone, or @ for the apex.

type
string

Narrows to one type; omitted, every type at the name goes.

string or Array of strings (RecordValue)

Narrows to one record, named the way a create names it: one string, or the segments of a TXT record. Compared canonically, so a value spelled another way still matches. Requires type.

priority
integer <int32>

MX and SRV keep their preference in its own column, so it narrows there rather than being part of value.

dry_run
boolean

When true, report what would go without removing anything.

Responses

Response samples

Content type
application/json
{
  • "applied": true,
  • "deleted": 3,
  • "diff": {
    },
  • "dry_run": false,
  • "records": [
    ]
}

Bulk insert DNS records into a zone

Insert many records into the named zone in one transaction. The zone serial is incremented once and a single NOTIFY is sent. Either all records are inserted or none are. With dry_run the same validation runs but nothing is applied.

Authorizations:
bearer_auth
Request Body schema: application/json
required
dry_run
boolean

When true, parse and validate without applying any change.

required
Array of objects (BulkRecordItem)
zone_name
required
string

Responses

Request samples

Content type
application/json
{
  • "dry_run": true,
  • "records": [
    ],
  • "zone_name": "example.com"
}

Response samples

Content type
application/json
{
  • "added": 3,
  • "applied": true,
  • "diff": {
    },
  • "dry_run": false,
  • "records": [
    ]
}

Get a specific DNS record

Authorizations:
bearer_auth
path Parameters
id
required
integer <int32>

The ID of the DNS record to retrieve.

Responses

Response samples

Content type
application/json
{
  • "record": {
    }
}

Update a specific DNS record

Applies the given fields and keeps the rest; without record:read on the record every field must be given, since an omitted one would be read from it. value is required when type changes, since a stored value is encoded per type.

Authorizations:
bearer_auth
path Parameters
id
required
integer <int32>

The ID of the DNS record to update.

Request Body schema: application/json
required
dry_run
boolean

Validate and report the change without writing it.

name
string or null
priority
integer or null <int32>

MX and SRV priority; other record types reject it.

ttl
integer or null <int32>

Records sharing a name and type share one TTL.

type
string or null
(RecordValue (RecordValue (string) or Array of RecordValue (strings))) or null

Responses

Request samples

Content type
application/json
{
  • "dry_run": false,
  • "name": "sub",
  • "priority": 10,
  • "ttl": 3600,
  • "type": "A",
  • "value": "192.168.1.100"
}

Response samples

Content type
application/json
{
  • "applied": true,
  • "diff": {
    },
  • "dry_run": false,
  • "record": {
    }
}

Delete a specific DNS record

Authorizations:
bearer_auth
path Parameters
id
required
integer <int32>

The ID of the DNS record to delete.

query Parameters
dry_run
boolean

Report what the request would do without applying it.

Responses

Response samples

Content type
application/json
{
  • "applied": true,
  • "deleted": 3,
  • "diff": {
    },
  • "dry_run": false,
  • "records": [
    ]
}

Notify

Send DNS NOTIFY messages to secondary servers.

Send DNS NOTIFY messages for all zones

Authorizations:
bearer_auth
query Parameters
bump_serial
boolean

Bump the serial first, so secondaries transfer even when nothing changed.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Send DNS NOTIFY messages for a zone

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone to notify secondaries about.

query Parameters
bump_serial
boolean

Bump the serial first, so secondaries transfer even when nothing changed.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Secondary

The secondary servers: each receives NOTIFY, may pull zones unsigned from its address, and is probed for the serial it serves.

List all secondaries

Lists every registered secondary, disabled ones included. An enabled secondary receives NOTIFY for all zones, may pull zones unsigned from its address, and is probed for the serial it serves.

Authorizations:
bearer_auth
query Parameters
limit
integer or null <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer or null <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Register a secondary

Registers a secondary by name and host[:port] address (port 53 when left out). It receives NOTIFY from the next change on and may pull zones unsigned from that address; a hostname is resolved when used. A signed transfer is authorized by its key instead, but NOTIFY still goes only to the registered secondaries. With notify_key_name, every NOTIFY to it is signed with that TSIG key and the answer's signature checked.

Authorizations:
bearer_auth
Request Body schema: application/json
required
address
required
string

host[:port], port 53 when left out; a hostname is resolved when used.

name
required
string

A plain identifier, since it travels in URL paths.

notify_key_name
string or null

TSIG key to sign NOTIFY to this server with; omitted sends it unsigned.

Responses

Request samples

Content type
application/json
{
  • "address": "ns2.example.net:53",
  • "name": "ns2",
  • "notify_key_name": "notify-key"
}

Response samples

Content type
application/json
{
  • "secondary": {
    }
}

Get a secondary

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the secondary.

Responses

Response samples

Content type
application/json
{
  • "secondary": {
    }
}

Update a secondary

Changes the address, the NOTIFY key (empty sends NOTIFY unsigned again), or enables or disables the secondary; an omitted field keeps its value. A disabled secondary receives no NOTIFY, may not transfer unsigned, and is not probed, but stays registered.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the secondary.

Request Body schema: application/json
required
address
string or null
enabled
boolean or null

false stops NOTIFY, unsigned transfers, and probes without forgetting the server.

notify_key_name
string or null

TSIG key to sign NOTIFY with; empty sends it unsigned again.

Responses

Request samples

Content type
application/json
{
  • "address": "192.0.2.7:53",
  • "enabled": true,
  • "notify_key_name": "notify-key"
}

Response samples

Content type
application/json
{
  • "secondary": {
    }
}

Delete a secondary

Forgets the secondary: it receives no further NOTIFY and its unsigned transfers are refused from the next request on.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the secondary.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Check a secondary

Resolves the secondary's address, asks it for the catalog zone's SOA serial and compares that with the serial Bindizr serves, and sends it a NOTIFY for the catalog zone. A disabled secondary is checked all the same. The NOTIFY is a real one, so the secondary may transfer the catalog as a result.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the secondary.

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ],
  • "catalog": {
    },
  • "catalog_serial": 42,
  • "catalog_zone_name": "catalog.bindizr",
  • "listener_error": "string",
  • "notifies": [
    ],
  • "resolve_error": "string",
  • "secondary": {
    },
  • "transfers": {
    }
}

List a secondary's transfers

The transfers Bindizr served the secondary's addresses, newest first, with how each zone was last served: AXFR, IXFR as a delta or as the whole zone, or refused and why. Bindizr keeps the latest transfer per zone and client address. A secondary with multiple addresses can have several entries for one zone.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the secondary.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

At most this many transfers, newest first; 1000 when omitted.

zone_name
string

Only the transfers of this zone.

Responses

Response samples

Content type
application/json
{
  • "address": "ns2.example.net:53",
  • "secondary_name": "ns2",
  • "summary": {
    },
  • "transfers": [
    ]
}

TSIG

Manage TSIG keys, each authenticating nsupdate and transfers into a role.

List TSIG keys

Lists TSIG keys without their secrets, every one or only those authenticating into role_name. Fetch a single key to read the secret.

Authorizations:
bearer_auth
query Parameters
role_name
string

Only the TSIG keys authenticating into this role.

limit
integer <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create a TSIG key

Creates a TSIG key. When secret is omitted a random secret is generated; when provided it must be valid base64 (imports an existing key). The key authenticates into role_name, whose grants decide what updates and transfers it may sign. The response includes the secret.

Authorizations:
bearer_auth
Request Body schema: application/json
required
algorithm
string or null

Defaults to hmac-sha256; also accepts hmac-sha384 and hmac-sha512.

name
required
string
role_name
required
string

The role whose grants decide what the key may sign; a NOTIFY-only key may name one without grants.

secret
string or null

Existing base64 secret to import; omit to generate a random one.

Responses

Request samples

Content type
application/json
{
  • "algorithm": "hmac-sha256",
  • "name": "update-key",
  • "role_name": "rfc2136-legacy",
  • "secret": "bXktMzItYnl0ZS1pbXBvcnQtc2VjcmV0LWV4YW1wbGU="
}

Response samples

Content type
application/json
{
  • "secret": "bXktMzItYnl0ZS1pbXBvcnQtc2VjcmV0LWV4YW1wbGU=",
  • "tsig_key": {
    }
}

Get a specific TSIG key

Returns one TSIG key including its secret.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the TSIG key.

Responses

Response samples

Content type
application/json
{
  • "secret": "bXktMzItYnl0ZS1pbXBvcnQtc2VjcmV0LWV4YW1wbGU=",
  • "tsig_key": {
    }
}

Delete a TSIG key

Deletes a TSIG key. Refused while it still signs a secondary's NOTIFY.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the TSIG key.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Token

API tokens, each authenticating into a role.

List API tokens

Lists API tokens without their secrets, every one or only those authenticating into role_name; a secret is shown once, in the create response.

Authorizations:
bearer_auth
query Parameters
role_name
string

Only the API tokens authenticating into this role.

limit
integer <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create an API token

Creates an API token in a role and returns its secret, the one time it is shown. The role's grants decide what the token may do.

Authorizations:
bearer_auth
Request Body schema: application/json
required
description
string or null

At most 255 characters.

expires_in_days
integer or null <int64>

Days until expiry, 1 to 36500; omit for a token that never expires.

name
required
string

Letters, digits, ., _, and -: one URL path segment.

role_name
required
string

The role whose grants decide what the token may do.

Responses

Request samples

Content type
application/json
{
  • "description": "ExternalDNS in the prod cluster",
  • "expires_in_days": 90,
  • "name": "external-dns",
  • "role_name": "external-dns-prod"
}

Response samples

Content type
application/json
{
  • "secret": "k7Qm2xLp9vRt4wYz8bNc1dFg6hJs3aEu",
  • "token": {
    }
}

Describe the API token making the request

The calling token's own metadata, never its secret; any token may read itself. With authentication disabled no token is presented, so this answers 401.

Authorizations:
bearer_auth

Responses

Response samples

Content type
application/json
{
  • "token": {
    }
}

List the grants of the calling API token's role

The grants of the calling token's role; any token may read its own. With authentication disabled no token is presented, so this answers 401.

Authorizations:
bearer_auth
query Parameters
limit
integer or null <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer or null <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Delete an API token

Deletes an API token; its role and the role's grants stay.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the API token.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Role

Roles and their grants: the actions API tokens and TSIG keys holding a role may perform.

Get the caller's permissions

What the calling token's role permits, computed from its grants: the actions held in all zones, including zones created later, and per zone where a zone-scoped grant adds to them. whole_zone lists the record actions held with no name or type limit, as export, versions, diffs, import and rollback need. With authentication disabled every action is permitted in all zones.

Authorizations:
bearer_auth

Responses

Response samples

Content type
application/json
{
  • "all_zones": {
    },
  • "zones": [
    ]
}

List all roles

Authorizations:
bearer_auth
query Parameters
limit
integer or null <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer or null <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create a role

Creates a role with no grants. API tokens and TSIG keys authenticate into a role, and its grants decide what they may do.

Authorizations:
bearer_auth
Request Body schema: application/json
required
description
string or null

At most 255 characters.

name
required
string

Letters, digits, ., _, and -: one URL path segment.

Responses

Request samples

Content type
application/json
{
  • "description": "ExternalDNS in the prod clusters",
  • "name": "external-dns-prod"
}

Response samples

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

Get a specific role

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the role.

Responses

Response samples

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

Delete a role

Deletes a role and its grants. Refused for the built-in admin role and while an API token or TSIG key still authenticates into it.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the role.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

List a role's grants

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the role.

query Parameters
limit
integer or null <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer or null <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Grant a role actions

Grants the role actions in the named zone, or in all zones when zone_name is omitted. The record name pattern (*, @, *.sub, or an exact relative name) and record types (* or a comma-separated list) narrow its record:* actions only. The built-in admin role cannot be changed.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the role.

Request Body schema: application/json
required
actions
required
Array of strings

The actions the grant permits, as <resource>:<action>.

record_name_pattern
string or null

* (any name), @ (apex), *.sub (subtree) or an exact relative name. Constrains record:* actions only. Defaults to *.

record_types
string or null

* or a comma-separated list of record types. Constrains record:* actions only. Defaults to *.

zone_name
string or null

Name of an existing zone; omit to cover all zones, including later ones. zone:create, secondary:* and access:manage need all zones.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "record_name_pattern": "*.apps",
  • "record_types": "A,AAAA,CNAME,TXT",
  • "zone_name": "example.com"
}

Response samples

Content type
application/json
{
  • "role_grant": {
    }
}

Revoke one of a role's grants

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the role.

id
required
integer <int32>

The id of the grant to revoke.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

DNSSEC

DNSSEC policies (the signing-parameter bundles zones sign under) and per-zone signing: enable, disable, status, DS records for the parent zone and the parent's check of them, key rollover, and re-signing.

List all DNSSEC policies

Lists every DNSSEC policy: the named signing-parameter bundles zones sign under. A default policy (ECDSA P-256 CSK, NSEC3, 14-day signatures re-signed with 5 days left) is seeded at startup.

Authorizations:
bearer_auth
query Parameters
limit
integer or null <int32> [ 1 .. 1000 ]

Items per page; the HTTP API defaults it, the daemon socket does not.

offset
integer or null <int64> >= 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create a DNSSEC policy

Creates a DNSSEC policy. The algorithm (ecdsap256sha256 by default; also ecdsap384sha384, ed25519, ed448, rsasha256, rsasha512), denial mode (nsec3 by default, or nsec), and key layout (split_keys) are fixed once created; the timing fields can be edited later. Omitted fields take the built-in defaults.

Authorizations:
bearer_auth
Request Body schema: application/json
required
algorithm
string or null

Defaults to ecdsap256sha256; also accepts ecdsap384sha384, ed25519, ed448, rsasha256, and rsasha512.

denial
string or null

Denial-of-existence mode: nsec3 (default, RFC 9276 parameters) or nsec, which leaves the zone's names walkable.

name
required
string
signature_refresh_days
integer or null <int32> >= 0

Re-sign when a signature has fewer than this many days left (default 5); must be below the validity.

signature_validity_days
integer or null <int32> >= 0

Days a new signature stays valid (default 14).

split_keys
boolean

A KSK/ZSK pair instead of one CSK, so the ZSK rolls without touching the parent DS.

zsk_lifetime_days
integer or null <int32> >= 0

Days an active ZSK may sign before the scheduler rolls it; 0 (the default) disables scheduled rolls.

Responses

Request samples

Content type
application/json
{
  • "algorithm": "ecdsap256sha256",
  • "denial": "nsec3",
  • "name": "strict",
  • "signature_refresh_days": 5,
  • "signature_validity_days": 14,
  • "split_keys": false,
  • "zsk_lifetime_days": 90
}

Response samples

Content type
application/json
{
  • "dnssec_policy": {
    }
}

Get a specific DNSSEC policy

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNSSEC policy.

Responses

Response samples

Content type
application/json
{
  • "dnssec_policy": {
    }
}

Edit a DNSSEC policy's timing

Edits the policy's signature validity, re-sign threshold, and scheduled ZSK lifetime; an omitted field keeps its value. The algorithm, denial mode, and key layout cannot change: move zones to another policy instead. Zones under the policy pick the new values up on their next signing pass or scheduler scan.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNSSEC policy.

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

Responses

Request samples

Content type
application/json
{
  • "signature_refresh_days": 7,
  • "signature_validity_days": 30,
  • "zsk_lifetime_days": 90
}

Response samples

Content type
application/json
{
  • "dnssec_policy": {
    }
}

Delete a DNSSEC policy

Deletes a DNSSEC policy. Refused for the built-in default policy and while any zone signs under it.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNSSEC policy.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Get a zone's DNSSEC status

Returns whether the zone is signed, the policy it signs under, its signing keys, their DS forms for the parent zone, the earliest stored signature expiration, and the zone serial. For an unsigned zone enabled is false with no policy and empty key and DS lists.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Change a zone's DNSSEC settings

Applies the given fields in one transaction; an omitted field keeps its value. policy_name moves a signed zone to another policy: the key layout must match the current policy's (it is fixed while signed; disable and re-enable to change it), a different denial mode replaces the chain under one serial, and a different algorithm starts an algorithm rollover that double-signs the zone until the old keys are removed after promotion and cache drain (RFC 6840, Section 5.11). parent_ns_addrs names the parent zone's nameservers asked for the zone's DS, as host[:port] entries; the list must name at least one server, and it applies to unsigned zones too.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Request Body schema: application/json
required
parent_ns_addrs
Array of strings or null

The parent zone's nameservers as host[:port] entries; must name at least one server.

policy_name
string or null

Policy to move the signed zone to; it must share the zone's key layout. A new denial mode replaces the chain under one serial, and a new algorithm starts a rollover.

Responses

Request samples

Content type
application/json
{
  • "parent_ns_addrs": [
    ],
  • "policy_name": "strict"
}

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Enable DNSSEC for a zone

Generates the zone's signing key(s) as the named DNSSEC policy prescribes (the built-in default policy — an ECDSA P-256 CSK with NSEC3 denial — when policy_name is omitted) and signs the whole zone. The response includes the DS records to register in the parent zone. parent_ns_addrs is required: it names the parent zone's nameservers that every later DS check asks.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Request Body schema: application/json
required
parent_ns_addrs
required
Array of strings

The parent zone's nameservers as host[:port] entries, asked for the zone's DS by every later check.

policy_name
string or null

Name of the DNSSEC policy to sign under; defaults to default.

Responses

Request samples

Content type
application/json
{
  • "parent_ns_addrs": [
    ],
  • "policy_name": "default"
}

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Disable DNSSEC for a zone

Deletes the zone's signing keys and derived records, so secondaries unsign via IXFR. Dropping the signatures while the parent zone still publishes a DS makes the zone bogus, so the zone's parent nameservers (parent_ns_addrs) are asked first: refused while any serves a DS for the zone (DNSSEC_DS_PUBLISHED) or fails to answer (DNSSEC_DS_UNVERIFIED). skip_ds_check=true skips the check; waiting out the DS TTL after its removal stays the caller's.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

query Parameters
skip_ds_check
boolean

Skip the parent DS check.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Ask the parent zone whether it serves the zone's DS

Asks the zone's parent nameservers (parent_ns_addrs) for the zone's DS records and reports the answer in delegation: published with the key tags and TTL served, or hidden. The same check gates disabling DNSSEC.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Start a key rollover for a zone

Pre-publishes a same-algorithm replacement key (RFC 7583) that signs no zone data until promoted; role selects the key for split-key zones. To change the algorithm, move the zone to a policy of the new algorithm (policy_name in PUT /zones/{name}/dnssec), which double-signs the zone through the transition (RFC 6840, Section 5.11).

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Request Body schema: application/json
required
role
string or null

Which key to roll: required for split-key zones (ksk or zsk), omitted for CSK zones.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Confirm the new DS is at the parent (ds-seen)

Promotes the pre-published key to active and retires the key it replaces, once the publish wait has passed and every one of the zone's parent nameservers (parent_ns_addrs) serves the new key's DS. The scheduler applies the same two conditions on every pass, so this is the way to finish a rollover now rather than the only way to finish it; refused with DNSSEC_DS_NOT_PUBLISHED while they do not, or DNSSEC_DS_UNVERIFIED when they cannot be asked or answer only in a digest type bindizr cannot compute. skip_ds_check=true takes the DS on the caller's word; skip_holddown=true promotes before the hold-down passes, at the cost of validation failures at resolvers still caching the previous DNSKEY set. Waiting out the parent's DS TTL after it appears stays the caller's. Retired keys are removed automatically once caches drain — for a SEP key that includes the parent's DS TTL, read from the answer that confirmed this promotion; ZSK rollovers involve no DS and are promoted automatically after their wait.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

query Parameters
skip_ds_check
boolean

Skip the parent DS check.

skip_holddown
boolean

Promote before the publish hold-down has passed.

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Re-sign a zone from scratch

Discards the zone's stored signatures and re-signs everything — a recovery hatch when stored signing state is doubted. Routine renewal happens automatically as records change and signatures approach expiry.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted successfully"
}

Publish the DS withdrawal (RFC 8078 delete CDS/CDNSKEY)

Replaces the zone's CDS/CDNSKEY records with the RFC 8078 delete pair (CDS 0 0 0 00), asking a CDS-consuming parent to remove the zone's DS records — the first step of going insecure. Once the parent DS is gone and its TTL has passed, disable DNSSEC.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

Cancel a published DS withdrawal

Removes the RFC 8078 delete pair; the per-key CDS/CDNSKEY records return with this signing pass.

Authorizations:
bearer_auth
path Parameters
name
required
string

The name of the DNS zone.

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "ds_records": [
    ],
  • "earliest_signature_expires_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "expired_signatures": 0,
  • "keys": [
    ],
  • "next_resign_at": "2019-08-24T14:15:22Z",
  • "parent_ns_addrs": [
    ],
  • "policy": {
    },
  • "serial": 7,
  • "signatures": 42,
  • "withdrawing": false,
  • "zone_name": "example.com"
}

ExternalDNS

Provider endpoints for the ExternalDNS webhook adapter; registered only when api.external_dns_enabled is set.

Canonicalize desired records without applying them

Backs the adapter's AdjustEndpoints step: returns each desired record in the canonical form applying it would store (uppercase type, sorted deduplicated presentation values), so external-dns compares desired state against the exact spelling GET /external-dns/records returns.

Authorizations:
bearer_auth
Request Body schema: application/json
required
required
Array of objects (ExternalDnsRecord)

Responses

Request samples

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

Response samples

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

Apply an ExternalDNS change set atomically

Applies creates, updates, and deletes in one transaction. Idempotent operations resolve to no change; only zones with a remaining delta advance their serial (once per request) and record IXFR history.

Authorizations:
bearer_auth
Request Body schema: application/json
required
Array of objects (ExternalDnsRecord)
Array of objects (ExternalDnsRecord)
Array of objects (ExternalDnsRecordUpdate)

Responses

Request samples

Content type
application/json
{
  • "creates": [
    ],
  • "deletes": [
    ],
  • "updates": [
    ]
}

Response samples

Content type
application/json
{
  • "added": 2,
  • "changed_zones": [
    ],
  • "deleted": 1
}

List the names ExternalDNS may manage

Returns every existing zone name when authentication is disabled. Otherwise, includes zones or subtrees covered by a grant containing all three actions: record:read, record:create, and record:delete. Entries are deduplicated. Each entry includes its descendants, so record-type and exact-name restrictions still need to be enforced when changes are applied.

Authorizations:
bearer_auth

Responses

Response samples

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

List the records of every ExternalDNS-managed zone

Records of all zones the calling token may manage, restricted to the supported record types (A, AAAA, CNAME, TXT): one record per name and type, with absolute owner names and sorted presentation-form values.

Authorizations:
bearer_auth

Responses

Response samples

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