Nameservers
Change a domain's nameservers and manage its child nameservers (glue records).
{id} is the domain id from GET /domains/mine. A domain with status pending_profile returns 409 DOMAIN_PENDING_PROFILE on every endpoint on this page.
Update nameservers
PUT
/domains/{id}/nameserversPoint the domain to new nameservers.
Prop
Type
curl -X PUT https://api.helipod.io/api/domains/42/nameservers \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{ "nameservers": ["ns1.example-dns.net", "ns2.example-dns.net"] }'{ "success": true, "message": "Nameservers updated" }- Fewer than 2 or more than 5 nameservers returns
422 VALIDATION_ERROR. - The first three nameservers are shown as
nameserver1tonameserver3inGET /domains/{id}. - Once the domain uses other nameservers, the DNS records managed through this API are no longer served. Changes take time to spread through DNS caches.
- To use nameservers under the domain itself (for example
ns1.example.com), create them as child nameservers first.
Child nameservers
Child nameservers (also called glue records or hosts) are nameservers named under your own domain, such as ns1.example.com, registered at the registry together with their IP address. Create them before you set them as the domain's nameservers.
Host object
{
"id": 7,
"hostname": "ns1",
"nameserver": "ns1.example.com",
"ip_address": "203.0.113.53",
"status": 1,
"status_label": "Active",
"created_at": "2026-10-16T09:30:00.000000Z",
"updated_at": "2026-10-16T09:30:00.000000Z"
}| Field | Description |
|---|---|
id | Host id. Use it as {hostId}. |
hostname | The label under your domain, for example ns1. |
nameserver | The full nameserver name. |
ip_address | IPv4 or IPv6 address. |
status, status_label | Status at the registry. |
created_at, updated_at | Timestamps. |
List child nameservers
GET
/domains/{id}/hostsAll child nameservers of the domain.
curl https://api.helipod.io/api/domains/42/hosts \
-H "Authorization: Bearer hel_your_key"{ "success": true, "data": [ { "id": 7, "hostname": "ns1", "nameserver": "ns1.example.com", "ip_address": "203.0.113.53", "status": 1, "status_label": "Active" } ] }Get a child nameserver
GET
/domains/{id}/hosts/{hostId}One child nameserver.
curl https://api.helipod.io/api/domains/42/hosts/7 \
-H "Authorization: Bearer hel_your_key"Returns { "success": true, "data": <host> }.
Create a child nameserver
POST
/domains/{id}/hostsRegister a nameserver under the domain.
Prop
Type
curl -X POST https://api.helipod.io/api/domains/42/hosts \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{ "hostname": "ns1", "ipAddress": "203.0.113.53" }'Returns 201 with { "success": true, "data": <host> }.
Update a child nameserver
PUT
/domains/{id}/hosts/{hostId}Change the label or IP address.
Prop
Type
curl -X PUT https://api.helipod.io/api/domains/42/hosts/7 \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{ "ipAddress": "203.0.113.54" }'Returns { "success": true, "data": <host> }.
Delete a child nameserver
DELETE
/domains/{id}/hosts/{hostId}Remove a child nameserver.
curl -X DELETE https://api.helipod.io/api/domains/42/hosts/7 \
-H "Authorization: Bearer hel_your_key"{ "success": true, "message": "Child nameserver deleted" }Stop using a child nameserver (in this domain and any other domain) before deleting it, or the registry may refuse the deletion.
Errors
| Status | code | When |
|---|---|---|
404 | DOMAIN_NOT_FOUND | Unknown or non-numeric domain id, or the domain is not registered at the registry yet. |
404 | NOT_FOUND | Unknown hostId, or a hostId that is not a number. |
409 | DOMAIN_PENDING_PROFILE | The domain waits for owner details. |
422 | VALIDATION_ERROR | Missing field, or the wrong number of nameservers. |
422 | REGISTRAR_REJECTED | The registry refused the change, for example an invalid IP address or a host still in use. |
502 | REGISTRAR_ERROR | The registry could not be reached. Retry later. |