API reference · Networking
Hosted DNS
16 operations of the Ankra Cloud API: Hosted DNS - zones on the Ankra Cloud nameservers, delegated subzones and their records.
List the account's hosted DNS zones and subzones in name order, with the zones still pending verification#
/v1/dns/zones- Operation
list_dns_zones- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
project_id | query | string | The project to read: a project's UUID, or all for every project the caller reaches. The X-Ankra-Project-Id header says the same; this parameter wins. Without either, an organisation-wide caller reads the default project and a member limited to projects reads their projects. 422 when it is neither, 403 for a project outside a member's reach, 404 for one the organisation does not list. Ignored while the account's organisation has projects off. |
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of zones.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of DnsZone | |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/dns/zones' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Claim a DNS zone to host on the Ankra Cloud nameservers#
/v1/dns/zones- Operation
create_dns_zone- Credentials
- API token, Portal session
- Requires
- Permission
operate
The zone starts as pending_verification: it holds no records and nothing is published. Publish the TXT record
in verification where the domain is served today, then call verify_dns_zone. A name is hosted once across
every account, and the first account to verify it takes it, so another account claiming the same name is no
obstacle here. 409 zone_exists when this account already claims or hosts the name. Audited as
dns.zone_created.
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string |
Responses
201The zone.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "example.com"
}'Get a hosted DNS zone#
/v1/dns/zones/{id}- Operation
get_dns_zone- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The zone.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/dns/zones/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Stop hosting a zone and delete its records#
/v1/dns/zones/{id}- Operation
delete_dns_zone- Credentials
- API token, Portal session
- Requires
- Permission
operate
A zone that still delegates subzones is refused with 409 zone_has_subzones; delete those first. Deleting a subzone
removes its delegation from the parent. The zone is removed from the nameservers before it is forgotten: 502
nameservers_unavailable leaves it in place to retry. A zone that is pending verification was never published and
is simply dropped. A zone the Ankra platform manages (managed_by ankra_platform: the organisation's zone and
the cluster zones below it) is refused with 409 zone_managed_by_platform; it goes with the organisation or
cluster in the platform. Audited as dns.zone_deleted.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
204Deleted.
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 502A service the control plane depends on (headscale) did not answer;
detailsays how. - defaultAny other error, usually 500.
Example
curl -X DELETE 'https://cloud.ankra.app/v1/dns/zones/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Read organisation access for proxied services#
/v1/dns/zones/{id}/access- Operation
get_dns_zone_access- Credentials
- Portal session, API token
- Requires
- Permission
read
Private access uses the account's linked Platform organisation and live membership checks. Empty roles admits every active member; otherwise exact organisation-wide role slugs or custom role UUIDs apply. project_id further limits access to the members who can reach that project: organisation-wide members and the project-only members assigned to it. Private zones reject direct A, AAAA, CNAME, HTTPS and SVCB records. Private ancestors also cover subzones; a child cannot weaken its parent. Unmanaged NS delegation records are rejected.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200Current access policy.application/json
| Field | Type | Description |
|---|---|---|
accessrequired | object | |
moderequired | string | One of public, organisation |
inherited_from | string | Private parent zone controlling this policy. |
organisation_id | string (uuid) | |
rolesrequired | array of string | |
project_id | string (uuid) | Admits only the members who can reach this project |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/dns/zones/<id>/access' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Configure organisation access for proxied services#
/v1/dns/zones/{id}/access- Operation
update_dns_zone_access- Credentials
- Portal session, API token
- Requires
- Permission
members.manage
Private access uses the account's linked Platform organisation and live membership checks. Empty roles admits every active member; otherwise exact organisation-wide role slugs or custom role UUIDs apply. project_id further limits access to the members who can reach that project: organisation-wide members and the project-only members assigned to it. Private zones reject direct A, AAAA, CNAME, HTTPS and SVCB records. Private ancestors also cover subzones; a child cannot weaken its parent. Unmanaged NS delegation records are rejected.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
moderequired | string | One of public, organisation |
rolesrequired | array of string | |
project_id | string | Admit only the members who can reach this Platform project. Leaving it out keeps the current value; an empty value clears it. |
Responses
200Current access policy.application/json
| Field | Type | Description |
|---|---|---|
accessrequired | object | |
moderequired | string | One of public, organisation |
inherited_from | string | Private parent zone controlling this policy. |
organisation_id | string (uuid) | |
rolesrequired | array of string | |
project_id | string (uuid) | Admits only the members who can reach this project |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X PUT 'https://cloud.ankra.app/v1/dns/zones/<id>/access' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"mode": "public",
"roles": [
"string"
]
}'List the records of a zone#
/v1/dns/zones/{id}/records- Operation
list_dns_records- Credentials
- API token, Portal session
- Requires
- Permission
read
A zone holds at most record_limit records plus the managed delegation records. Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of the zone's records, newest first.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of DnsRecord | |
idrequired | string | |
zone_idrequired | string | |
namerequired | string | Relative to the zone: @ for the apex, www, a.b, *. |
typerequired | string | One of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP |
contentrequired | string | The stored origin; preserved when proxied DNS publishes relay addresses. |
proxiedrequired | boolean | Both A and AAAA answers use the HTTP/HTTPS relay with automatic WAF. |
proxy_request_body_limit_bytesrequired | integer | null | Largest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB). |
ttlrequired | integer | |
priorityrequired | integer | null | MX and SRV only. |
commentrequired | string | null | A note for people; never published in DNS. |
managedrequired | boolean | Apex NS and subzone delegations, owned by the platform and not editable. |
sourcerequired | string | Who owns a record: a customer (user), the hosted DNS service's own delegation rows (system), the Ankra platform through the fleet routes (platform) or a cluster's external-dns through the webhook (external-dns).One of user, system, platform, external-dns |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/dns/zones/<id>/records' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Add a record to a zone#
/v1/dns/zones/{id}/records- Operation
create_dns_record- Credentials
- API token, Portal session
- Requires
- Permission
operate
name is relative to the zone (@ for the apex, www, a.b, *); a fully qualified name is shortened. Content
is validated per type (400 with a code such as invalid_ipv4 or invalid_hostname). A CNAME must be the only
record at its name (409 cname_conflict) and a zone holds at most record_limit records (409
record_limit_reached). ttl is clamped to 30-86400 seconds (default 300, "Auto"); priority applies to MX
(default 10) and SRV (default 0). comment is for people and never published. A failed publish sets the zone's
sync_error. A zone that is pending verification takes no records: 409 zone_not_verified. Audited as
dns.record_created.
proxied: true enables HTTP/HTTPS delivery through the dual-stack relay with its zone WAF policy automatically applied (blocking by default).
The record must be AAAA at an exact hostname (no wildcard), with content equal to a running load balancer's
public IPv6 address in this account, or to the public IPv6 of the server of one of this account's dev clusters
(k3s's bundled Traefik answers plain HTTP on its port 80, so an IPv6-only trial dev cluster is reachable over
IPv4 and IPv6). The load balancer needs a plaintext port 80 frontend without an HTTPS redirect; TLS terminates
at the relay, which passes HTTP-01 challenges it holds no token for on to the origin, so cert-manager on the
origin still completes them. DNS answers both relay A and AAAA addresses while content keeps the origin IPv6.
Other stored A/AAAA rows at that hostname are retained but suppressed while proxying is active. Validation
reasons include proxy_requires_ipv6_load_balancer, proxy_server_not_dev_cluster (the address is one of this
account's servers that runs no dev cluster), dns_proxy_origin_http_required, proxy_origin_conflict and
proxy_unavailable.
proxy_request_body_limit_bytes raises (or lowers) the largest request body the relay accepts for the hostname,
from 1048576 (1 MiB) to 5368709120 (5 GiB); null or 0 keeps the default of 8388608 (8 MiB). Above 8 MiB the
hostname is an upload endpoint: the WAF inspects the first 8 MiB and streams the rest to the origin, inspects
an unstructured body as raw bytes and accepts any content type; a form, multipart, JSON or XML body must
still fit in 8 MiB (413). Only a proxied record takes a limit: 400 proxy_request_body_limit_requires_proxied,
and 400 invalid_proxy_request_body_limit outside the bounds.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string | |
typerequired | string | One of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP |
contentrequired | string | |
proxied | boolean | Enable the dual-stack HTTP/HTTPS relay and automatic WAF for this AAAA origin. |
proxy_request_body_limit_bytes | integer | null | Largest request body in bytes the relay accepts for this proxied hostname, 1048576 to 5368709120; null or 0 is the default (8388608). |
ttl | integer | |
priority | integer | |
comment | string | null |
Responses
201The record.application/json
| Field | Type | Description |
|---|---|---|
recordrequired | DnsRecord | |
idrequired | string | |
zone_idrequired | string | |
namerequired | string | Relative to the zone: @ for the apex, www, a.b, *. |
typerequired | string | One of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP |
contentrequired | string | The stored origin; preserved when proxied DNS publishes relay addresses. |
proxiedrequired | boolean | Both A and AAAA answers use the HTTP/HTTPS relay with automatic WAF. |
proxy_request_body_limit_bytesrequired | integer | null | Largest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB). |
ttlrequired | integer | |
priorityrequired | integer | null | MX and SRV only. |
commentrequired | string | null | A note for people; never published in DNS. |
managedrequired | boolean | Apex NS and subzone delegations, owned by the platform and not editable. |
sourcerequired | string | Who owns a record: a customer (user), the hosted DNS service's own delegation rows (system), the Ankra platform through the fleet routes (platform) or a cluster's external-dns through the webhook (external-dns).One of user, system, platform, external-dns |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones/<id>/records' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"type": "A",
"content": "string"
}'Change a record's name, content, proxy mode, TTL, priority or comment#
/v1/dns/zones/{id}/records/{record_id}- Operation
update_dns_record- Credentials
- API token, Portal session
- Requires
- Permission
operate
Fields left out keep their value; the type is fixed (delete and recreate to change it). Managed records (apex NS,
subzone delegations) are refused with 409 managed_record, and records with source external-dns (a
cluster's external-dns writes them again on its next sync) with 409 record_managed_by_external_dns. Audited as
dns.record_updated.
proxied: true has the same origin (a load balancer or a dev cluster's server) and plaintext port 80 requirements as record creation and
automatically applies the zone WAF policy (blocking by default). proxied: false restores the stored direct A/AAAA records; omission
preserves the current mode. The type and content returned by the API always describe the origin record.
proxy_request_body_limit_bytes sets the proxied hostname's request body limit as on creation; null or 0
restores the default, omission keeps it, and proxied: false drops it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
record_idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
name | string | |
content | string | |
proxied | boolean | Enable the dual-stack HTTP/HTTPS relay and automatic WAF for this AAAA origin. |
proxy_request_body_limit_bytes | integer | null | Largest request body in bytes the relay accepts for this proxied hostname, 1048576 to 5368709120; null or 0 is the default (8388608). |
ttl | integer | |
priority | integer | |
comment | string | An empty string clears the comment. |
Responses
200The changed record.application/json
| Field | Type | Description |
|---|---|---|
recordrequired | DnsRecord | |
idrequired | string | |
zone_idrequired | string | |
namerequired | string | Relative to the zone: @ for the apex, www, a.b, *. |
typerequired | string | One of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP |
contentrequired | string | The stored origin; preserved when proxied DNS publishes relay addresses. |
proxiedrequired | boolean | Both A and AAAA answers use the HTTP/HTTPS relay with automatic WAF. |
proxy_request_body_limit_bytesrequired | integer | null | Largest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB). |
ttlrequired | integer | |
priorityrequired | integer | null | MX and SRV only. |
commentrequired | string | null | A note for people; never published in DNS. |
managedrequired | boolean | Apex NS and subzone delegations, owned by the platform and not editable. |
sourcerequired | string | Who owns a record: a customer (user), the hosted DNS service's own delegation rows (system), the Ankra platform through the fleet routes (platform) or a cluster's external-dns through the webhook (external-dns).One of user, system, platform, external-dns |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X PATCH 'https://cloud.ankra.app/v1/dns/zones/<id>/records/<record_id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"content": "string",
"proxied": false,
"proxy_request_body_limit_bytes": 0,
"ttl": 0,
"priority": 0,
"comment": "string"
}'Delete a record#
/v1/dns/zones/{id}/records/{record_id}- Operation
delete_dns_record- Credentials
- API token, Portal session
- Requires
- Permission
operate
Managed records are refused with 409 managed_record, records with source external-dns with 409 record_managed_by_external_dns. Audited as dns.records_deleted.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
record_idrequired | path | string |
Responses
204Deleted.
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X DELETE 'https://cloud.ankra.app/v1/dns/zones/<id>/records/<record_id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Delete up to 500 records of a zone at once#
/v1/dns/zones/{id}/records/bulk-delete- Operation
bulk_delete_dns_records- Credentials
- API token, Portal session
- Requires
- Permission
operate
Managed records and ids the zone does not have are skipped and listed with their reason; each affected record
set is republished once. Audited as one dns.records_deleted.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
idsrequired | array of string |
Responses
200How many records were deleted and which were skipped.application/json
| Field | Type | Description |
|---|---|---|
deletedrequired | integer | |
skippedrequired | array of object | |
idrequired | string | |
reasonrequired | string | One of not_found, managed_record, record_managed_by_external_dns |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones/<id>/records/bulk-delete' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"ids": [
"string"
]
}'List the subzones a zone delegates#
/v1/dns/zones/{id}/subzones- Operation
list_dns_subzones- Credentials
- API token, Portal session
- Requires
- Permission
read
Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of the subzones, newest first.application/json · DnsZoneList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of DnsZone | |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/dns/zones/<id>/subzones' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Host <label>.<zone> as a zone of its own, delegated from this zone#
/v1/dns/zones/{id}/subzones- Operation
create_dns_subzone- Credentials
- API token, Portal session
- Requires
- Permission
operate
The subzone gets its own records and the parent gets managed NS records at label, so a team can own the
subdomain. It needs no verification of its own: the parent is verified. Refused with 409
records_exist_at_subdomain when the parent already holds records at or below the name (they would stop
answering), 409 subzone_exists when the name is already hosted, 409 zone_not_verified when the parent is
pending verification, and 400 invalid_subzone_label. Audited as dns.subzone_created.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
labelrequired | string |
Responses
201The subzone.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones/<id>/subzones' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"label": "dev"
}'Republish every record of the zone to the nameservers#
/v1/dns/zones/{id}/sync- Operation
sync_dns_zone- Credentials
- API token, Portal session
- Requires
- Permission
operate
Clears sync_error when every record set is accepted; otherwise the zone carries the new failure. 409
zone_not_verified for a zone that is pending verification.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The zone after the push.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones/<id>/sync' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Verify ownership of a pending zone and start hosting it#
/v1/dns/zones/{id}/verify- Operation
verify_dns_zone- Credentials
- API token, Portal session
- Requires
- Permission
operate
Looks the zone's verification TXT record up in public DNS. When it is there the zone becomes active, gets
its managed NS records for nameservers and is published; it answers publicly once the registrar delegates
the domain to them. 409 verification_record_not_found while the record is not visible yet (a new record can
take a few minutes), 409 zone_exists when another account verified the name first, and 502
verification_lookup_failed when public DNS gave no answer, which is worth a retry. A zone that is already
active is returned unchanged. Audited as dns.zone_verified.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The zone, now active.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 502A service the control plane depends on (headscale) did not answer;
detailsays how. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/dns/zones/<id>/verify' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Configure WAF protection for the zone's Proxied records#
/v1/dns/zones/{id}/waf- Operation
update_dns_zone_waf- Credentials
- API token, Portal session
- Requires
- Permission
operate
Replace the verified zone's WAF policy. Defaults are block/standard. Monitor logs attack matches without blocking them; off skips inspection. Strict uses OWASP CRS paranoia level 2; standard uses level 1. Applies to this zone only, including future Proxied records, without changing DNS answers or origin routing. The relay refreshes settings within a few seconds. DNS-only records and separately managed subzones are unaffected. Requires operate permission and is audited as dns.waf_updated. Unknown modes or sensitivities are rejected; pending verification returns 409 and another account's zone returns 404.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json · DnsWafPolicy
| Field | Type | Description |
|---|---|---|
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
Responses
200The zone with its saved WAF settings.application/json
| Field | Type | Description |
|---|---|---|
zonerequired | DnsZone | A hosted DNS zone. A subzone has parent_zone_id and is delegated from that zone with managed NS records. A new zone is pending_verification until its verification record is found; it keeps its id when it becomes active. |
project_id | string (uuid) | The project this belongs to. Present only while the account's organisation scopes by project. |
waf | DnsWafPolicy | |
moderequired | string | One of block, monitor, off |
sensitivityrequired | string | One of standard, strict |
idrequired | string | |
namerequired | string | |
statusrequired | string | pending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active |
verificationrequired | DnsZoneVerification | null | The record that proves ownership; null once the zone is active. |
record_namerequired | string | The absolute name of the record. |
record_typerequired | string | One of TXT |
record_valuerequired | string | |
parent_zone_idrequired | string | null | |
record_countrequired | integer | |
record_limitrequired | integer | How many records the zone may hold. |
nameserversrequired | array of string | The hostnames to delegate the domain to at its registrar. |
sync_errorrequired | string | null | The last failure publishing the zone; null once a push succeeds. |
managed_by | string | null | ankra_platform for an organisation zone the Ankra platform delegated into the account and the cluster zones it created below it: members edit their records but deleting the zone answers 409 zone_managed_by_platform. Null for every other zone.One of ankra_platform |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X PUT 'https://cloud.ankra.app/v1/dns/zones/<id>/waf' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"mode": "block",
"sensitivity": "standard"
}'