Skip to content

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

idstringrequired
The domain ID (dom_…).

Body

nameserversarray of stringrequired
The 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 string
Glue IP addresses for nameservers under the domain itself, in the same order as nameservers. Leave an entry empty when that nameserver needs none.
recoveryValuesobject
Answers 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

POST /api/v2/domains/{id}/nameservers
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"
]
}'

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.

Response 202
{
"operation": {
"status": "in_progress",
"jobId": "dbj_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/dbj_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Where 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.
jobIdstring
pollUrlstring or null
Where 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.

400The 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.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is domain_not_found.
409The nameservers cannot be changed now. actions.canChangeNameservers in the body gives the reason.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.