Change domain nameservers
POST /api/v2/domains/{id}/nameservers
Replaces the nameservers of the domain. Check actions.canChangeNameservers.allowed on GET /api/v2/domains/{id}/nameservers first. A blocked change returns 409 nameserver_update_blocked with the reason. The change runs as a job. Follow operation.pollUrl until it finishes (Jobs). A refusal by the registry shows up as a failed job. Switching to Hostup’s nameservers (primary.ns.hostup.se and secondary.ns.hostup.se) first prepares the domain’s DNS zone on them. A nameserver change while automatic DNSSEC is on pauses it for a cooldown period.
Authentication: An API key with the scope write:domains. About keys and scopes
Request
Path parameters
idstringrequiredThe domain ID (
dom_…).Body
nameserversarray of stringrequiredThe new nameserver hostnames, 1 to 10. Empty entries are ignored. Most domains need at least two. A .se or .nu domain accepts one external nameserver. Hostup’s nameservers are always sent as the pair
primary.ns.hostup.se and secondary.ns.hostup.se. Send each entry as a string. Another type, such as a number, answers 500.nsipsarray of stringGlue IP addresses for nameservers under the domain itself, in the same order as
nameservers. Leave an entry empty when that nameserver needs none.recoveryValuesobjectAnswers to the fields a failed nameserver job listed in
progressDetails.contactRecovery.fields, keyed by key. Fields with target: account are changed in the account details instead.Example
curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/nameservers" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nameservers": [ "primary.ns.hostup.se", "secondary.ns.hostup.se" ] }'curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/nameservers" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nameservers": [ "ns1.example.net", "ns2.example.net" ] }'curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/nameservers" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nameservers": [ "ns1.example.com", "ns2.example.com" ], "nsips": [ "192.0.2.53", "192.0.2.54" ] }'Responses
202 The change is queued. Poll operation.pollUrl. A registry refusal, an active domain lock, a nameserver without a glue record or a delegation check that could not run all end as a failed job. error is then Job failed. and does not say which. When the registry needs more account details first, progressDetails.contactRecovery lists them, with the reason in reason.
{ "operation": { "status": "in_progress", "jobId": "dbj_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/jobs/dbj_01hxa3b4c5d6e7f8g9h0j1k2m3" }}Response fields
operationobjectstatusstringWhere the job is. A
202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.jobIdstringpollUrlstring or nullWhere to poll the job while it runs.
null when status is already completed or failed.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The nameserver list is invalid: too few, too many or only one of Hostup’s two nameservers. A body without nameservers, or where nameservers or nsips is not an array, answers 422 with code invalid_request instead. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is domain_not_found. |
| 409 | The nameservers cannot be changed now. actions.canChangeNameservers in the body gives the reason. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists. |