AnkraDocs
Console

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#

GET/v1/dns/zones
Operation
list_dns_zones
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
project_idquerystringThe 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.
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of zones.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of DnsZone
project_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

POST/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

Request body fields
FieldTypeDescription
namerequiredstring

Responses

201The zone.application/json

201 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (date-time)
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

GET/v1/dns/zones/{id}
Operation
get_dns_zone
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The zone.application/json

200 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/dns/zones/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Stop hosting a zone and delete its records#

DELETE/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

Parameters
NameInTypeDescription
idrequiredpathstring

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_credentials on 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; detail says how.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/dns/zones/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Read organisation access for proxied services#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200Current access policy.application/json

200 response fields
FieldTypeDescription
accessrequiredobject
moderequiredstringOne of public, organisation
inherited_fromstringPrivate parent zone controlling this policy.
organisation_idstring (uuid)
rolesrequiredarray of string
project_idstring (uuid)Admits only the members who can reach this project
  • 400The request is invalid; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/dns/zones/<id>/access' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Configure organisation access for proxied services#

PUT/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
moderequiredstringOne of public, organisation
rolesrequiredarray of string
project_idstringAdmit 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

200 response fields
FieldTypeDescription
accessrequiredobject
moderequiredstringOne of public, organisation
inherited_fromstringPrivate parent zone controlling this policy.
organisation_idstring (uuid)
rolesrequiredarray of string
project_idstring (uuid)Admits only the members who can reach this project
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of the zone's records, newest first.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of DnsRecord
idrequiredstring
zone_idrequiredstring
namerequiredstringRelative to the zone: @ for the apex, www, a.b, *.
typerequiredstringOne of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP
contentrequiredstringThe stored origin; preserved when proxied DNS publishes relay addresses.
proxiedrequiredbooleanBoth A and AAAA answers use the HTTP/HTTPS relay with automatic WAF.
proxy_request_body_limit_bytesrequiredinteger | nullLargest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB).
ttlrequiredinteger
priorityrequiredinteger | nullMX and SRV only.
commentrequiredstring | nullA note for people; never published in DNS.
managedrequiredbooleanApex NS and subzone delegations, owned by the platform and not editable.
sourcerequiredstringWho 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_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/dns/zones/<id>/records' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Add a record to a zone#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
namerequiredstring
typerequiredstringOne of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP
contentrequiredstring
proxiedbooleanEnable the dual-stack HTTP/HTTPS relay and automatic WAF for this AAAA origin.
proxy_request_body_limit_bytesinteger | nullLargest request body in bytes the relay accepts for this proxied hostname, 1048576 to 5368709120; null or 0 is the default (8388608).
ttlinteger
priorityinteger
commentstring | null

Responses

201The record.application/json

201 response fields
FieldTypeDescription
recordrequiredDnsRecord
idrequiredstring
zone_idrequiredstring
namerequiredstringRelative to the zone: @ for the apex, www, a.b, *.
typerequiredstringOne of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP
contentrequiredstringThe stored origin; preserved when proxied DNS publishes relay addresses.
proxiedrequiredbooleanBoth A and AAAA answers use the HTTP/HTTPS relay with automatic WAF.
proxy_request_body_limit_bytesrequiredinteger | nullLargest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB).
ttlrequiredinteger
priorityrequiredinteger | nullMX and SRV only.
commentrequiredstring | nullA note for people; never published in DNS.
managedrequiredbooleanApex NS and subzone delegations, owned by the platform and not editable.
sourcerequiredstringWho 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_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

PATCH/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

Parameters
NameInTypeDescription
idrequiredpathstring
record_idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
namestring
contentstring
proxiedbooleanEnable the dual-stack HTTP/HTTPS relay and automatic WAF for this AAAA origin.
proxy_request_body_limit_bytesinteger | nullLargest request body in bytes the relay accepts for this proxied hostname, 1048576 to 5368709120; null or 0 is the default (8388608).
ttlinteger
priorityinteger
commentstringAn empty string clears the comment.

Responses

200The changed record.application/json

200 response fields
FieldTypeDescription
recordrequiredDnsRecord
idrequiredstring
zone_idrequiredstring
namerequiredstringRelative to the zone: @ for the apex, www, a.b, *.
typerequiredstringOne of A, AAAA, CNAME, MX, TXT, SRV, NS, CAA, DS, PTR, HTTPS, SVCB, TLSA, SSHFP
contentrequiredstringThe stored origin; preserved when proxied DNS publishes relay addresses.
proxiedrequiredbooleanBoth A and AAAA answers use the HTTP/HTTPS relay with automatic WAF.
proxy_request_body_limit_bytesrequiredinteger | nullLargest request body in bytes the relay accepts for this proxied hostname; null is the default (8388608, 8 MiB).
ttlrequiredinteger
priorityrequiredinteger | nullMX and SRV only.
commentrequiredstring | nullA note for people; never published in DNS.
managedrequiredbooleanApex NS and subzone delegations, owned by the platform and not editable.
sourcerequiredstringWho 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_atrequiredstring (date-time)
updated_atrequiredstring (date-time)
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

DELETE/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

Parameters
NameInTypeDescription
idrequiredpathstring
record_idrequiredpathstring

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_credentials on 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

bash
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#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
idsrequiredarray of string

Responses

200How many records were deleted and which were skipped.application/json

200 response fields
FieldTypeDescription
deletedrequiredinteger
skippedrequiredarray of object
idrequiredstring
reasonrequiredstringOne of not_found, managed_record, record_managed_by_external_dns
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of the subzones, newest first.application/json · DnsZoneList

200 response fields
FieldTypeDescription
itemsrequiredarray of DnsZone
project_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
labelrequiredstring

Responses

201The subzone.application/json

201 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (date-time)
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The zone after the push.application/json

200 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (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_credentials on 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

bash
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#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The zone, now active.application/json

200 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (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_credentials on 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; detail says how.
  • defaultAny other error, usually 500.

Example

bash
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#

PUT/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · DnsWafPolicy

Request body fields
FieldTypeDescription
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict

Responses

200The zone with its saved WAF settings.application/json

200 response fields
FieldTypeDescription
zonerequiredDnsZoneA 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_idstring (uuid)The project this belongs to. Present only while the account's organisation scopes by project.
wafDnsWafPolicy
moderequiredstringOne of block, monitor, off
sensitivityrequiredstringOne of standard, strict
idrequiredstring
namerequiredstring
statusrequiredstringpending_verification holds no records and publishes nothing; record and subzone changes answer 409 zone_not_verified.One of pending_verification, active
verificationrequiredDnsZoneVerification | nullThe record that proves ownership; null once the zone is active.
record_namerequiredstringThe absolute name of the record.
record_typerequiredstringOne of TXT
record_valuerequiredstring
parent_zone_idrequiredstring | null
record_countrequiredinteger
record_limitrequiredintegerHow many records the zone may hold.
nameserversrequiredarray of stringThe hostnames to delegate the domain to at its registrar.
sync_errorrequiredstring | nullThe last failure publishing the zone; null once a push succeeds.
managed_bystring | nullankra_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_atrequiredstring (date-time)
  • 400The request is invalid; detail says 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_credentials on 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

bash
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"
}'