Change the hostname of a VPS
PUT /api/v2/vps/{id}/hostname
Sets a new hostname on a VPS. The VPS is renamed at once and its name in the client area follows. A display name set with PUT /api/v2/vps/{id}/metadata is removed. The operating system picks up the new hostname the next time the VPS restarts. Reverse DNS is not changed. A name without a dot is saved with .local added. The saved name is in hostname.
Authentication: An API key with the scope write:vm. About keys and scopes
Request
Path parameters
idstringrequiredThe VPS ID (
vps_…).Body
hostnamestringrequiredThe new hostname, at most 253 characters. Letters, digits, hyphens and dots. No label may start or end with a hyphen.
Example
curl -X PUT "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/hostname" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "hostname": "web-01.example.com" }'Responses
200 The hostname was changed.
{ "hostname": "web-01.example.com", "reloadRecommended": true, "accountInactive": false, "accountStatus": null, "cacheCleared": false, "hostnameNormalized": false, "serviceRecordSynced": true, "reverseDnsProtection": null, "actions": { "canChange": { "allowed": true, "reason": null } }, "validationRules": { "maxLengthChars": 253, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$", "patternDescription": "Valid FQDN: labels 1-63 chars, alphanumeric with hyphens, no leading/trailing hyphens." }, "updatedAt": "2026-04-27T12:00:00.000Z"}Response fields
hostnamestring or nullThe hostname as saved.
reloadRecommendedbooleanAlways true after a change. Restart the VPS to apply the hostname inside the operating system.
accountInactivebooleanAlways false after a successful change.
accountStatusstring or nullAlways null after a successful change.
cacheClearedbooleanAlways false in this response.
actionsobjectWhat the caller can do with the hostname now.
canChangeobjectWhether the hostname can be changed. False when the VPS service has ended.
allowedbooleanTrue when a change is allowed now.
reasonstring or nullWhy a change is not allowed. Null when it is.
validationRulesobjectThe rules a new hostname must follow.
maxLengthCharsintegerMaximum length in characters.
patternstringRegular expression the hostname must match.
patternDescriptionstringThe pattern in words.
hostnameNormalizedboolean or nullAlways false in this response, also when
.local was added. Compare hostname with the name you sent.serviceRecordSyncedboolean or nullTrue when the name shown in the client area was updated too. When false, the client area may show the old name for a while.
reverseDnsProtectionobject | nullAlways null. Reverse DNS is checked after the response is sent.
statusstringnot_changed, restored or partial_failure. One of not_changed, restored, partial_failure.monitoredIpCountintegerHow many IP addresses were checked.
changesDetectedintegerHow many reverse DNS records changed.
restoredIpsarray of stringIP addresses whose reverse DNS was put back.
failedIpsarray of stringIP addresses whose reverse DNS could not be put back.
detailstring or nullA sentence about the result. Null when nothing changed.
updatedAtstringWhen the change was made.
Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 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 vps_not_found. |
| 409 | The VPS is still being set up. code is vps_not_ready. Retry after recovery.retryAfterSeconds. |
| 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. |