API reference · Networking

Hosted DNS

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

GET/v1/dns/zones

Operation: list_dns_zones
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`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

200 response fields
Field	Type	Description
`items`required	array of DnsZone
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	string (date-time)
`next_cursor`required	string \| null	Pass 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).
defaultAny other error, usually 500.

Example

bash

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

Host a DNS zone on the Ankra Cloud nameservers#

POST/v1/dns/zones

Operation: create_dns_zone
Credentials: API token, Portal session
Requires: Permission operate

The zone starts with managed NS records for nameservers and answers publicly once the registrar delegates the domain to them. A name is hosted once across every account: 409 zone_exists. Audited as dns.zone_created.

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string

Responses

201The zone.application/json

201 response fields
Field	Type	Description
`zone`required	DnsZone	A hosted DNS zone. A subzone has `parent_zone_id` and is delegated from that zone with managed NS records.
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	string (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.
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
Name	In	Type	Description
`id`required	path	string

Responses

200The zone.application/json

200 response fields
Field	Type	Description
`zone`required	DnsZone	A hosted DNS zone. A subzone has `parent_zone_id` and is delegated from that zone with managed NS records.
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	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_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.
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. Audited as dns.zone_deleted.

Parameters

Parameters
Name	In	Type	Description
`id`required	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_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.
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"

List every record of a zone in name and type order (`next_cursor` is always null)#

GET/v1/dns/zones/{id}/records

Operation: list_dns_records
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The zone's records, at most record_limit plus managed delegations.application/json

200 response fields
Field	Type	Description
`items`required	array of DnsRecord
`id`required	string
`zone_id`required	string
`name`required	string	Relative to the zone: `@` for the apex, `www`, `a.b`, `*`.
`type`required	string	One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, `DS`, `PTR`, `HTTPS`, `SVCB`, `TLSA`, `SSHFP`
`content`required	string
`ttl`required	integer
`priority`required	integer \| null	MX and SRV only.
`comment`required	string \| null	A note for people; never published in DNS.
`managed`required	boolean	Apex NS and subzone delegations, owned by the platform and not editable.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`next_cursor`required	null

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.
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. Audited as dns.record_created.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`type`required	string	One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, `DS`, `PTR`, `HTTPS`, `SVCB`, `TLSA`, `SSHFP`
`content`required	string
`ttl`	integer
`priority`	integer
`comment`	string \| null

Responses

201The record.application/json

201 response fields
Field	Type	Description
`record`required	DnsRecord
`id`required	string
`zone_id`required	string
`name`required	string	Relative to the zone: `@` for the apex, `www`, `a.b`, `*`.
`type`required	string	One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, `DS`, `PTR`, `HTTPS`, `SVCB`, `TLSA`, `SSHFP`
`content`required	string
`ttl`required	integer
`priority`required	integer \| null	MX and SRV only.
`comment`required	string \| null	A note for people; never published in DNS.
`managed`required	boolean	Apex NS and subzone delegations, owned by the platform and not editable.
`created_at`required	string (date-time)
`updated_at`required	string (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.
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, 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. Audited as dns.record_updated.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`record_id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`	string
`content`	string
`ttl`	integer
`priority`	integer
`comment`	string	An empty string clears the comment.

Responses

200The changed record.application/json

200 response fields
Field	Type	Description
`record`required	DnsRecord
`id`required	string
`zone_id`required	string
`name`required	string	Relative to the zone: `@` for the apex, `www`, `a.b`, `*`.
`type`required	string	One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, `DS`, `PTR`, `HTTPS`, `SVCB`, `TLSA`, `SSHFP`
`content`required	string
`ttl`required	integer
`priority`required	integer \| null	MX and SRV only.
`comment`required	string \| null	A note for people; never published in DNS.
`managed`required	boolean	Apex NS and subzone delegations, owned by the platform and not editable.
`created_at`required	string (date-time)
`updated_at`required	string (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.
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",
  "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. Audited as dns.records_deleted.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`record_id`required	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_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.
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
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`ids`required	array of string

Responses

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

200 response fields
Field	Type	Description
`deleted`required	integer
`skipped`required	array of object
`id`required	string
`reason`required	string	One of `not_found`, `managed_record`

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.
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 (`next_cursor` is always null)#

GET/v1/dns/zones/{id}/subzones

Operation: list_dns_subzones
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The subzones in name order.application/json · DnsZoneList

200 response fields
Field	Type	Description
`items`required	array of DnsZone
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	string (date-time)
`next_cursor`required	null

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.
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. 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, and 400 invalid_subzone_label. Audited as dns.subzone_created.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`label`required	string

Responses

201The subzone.application/json

201 response fields
Field	Type	Description
`zone`required	DnsZone	A hosted DNS zone. A subzone has `parent_zone_id` and is delegated from that zone with managed NS records.
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	string (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.
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.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The zone after the push.application/json

200 response fields
Field	Type	Description
`zone`required	DnsZone	A hosted DNS zone. A subzone has `parent_zone_id` and is delegated from that zone with managed NS records.
`id`required	string
`name`required	string
`parent_zone_id`required	string \| null
`record_count`required	integer
`record_limit`required	integer	How many records the zone may hold.
`nameservers`required	array of string	The hostnames to delegate the domain to at its registrar.
`sync_error`required	string \| null	The last failure publishing the zone; null once a push succeeds.
`created_at`required	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_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.
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"