Skip to content

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

idstringrequired
The VPS ID (vps_…).

Body

hostnamestringrequired
The new hostname, at most 253 characters. Letters, digits, hyphens and dots. No label may start or end with a hyphen.

Example

PUT /api/v2/vps/{id}/hostname
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.

Response 200
{
"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 null
The hostname as saved.
reloadRecommendedboolean
Always true after a change. Restart the VPS to apply the hostname inside the operating system.
accountInactiveboolean
Always false after a successful change.
accountStatusstring or null
Always null after a successful change.
cacheClearedboolean
Always false in this response.
actionsobject
What the caller can do with the hostname now.
canChangeobject
Whether the hostname can be changed. False when the VPS service has ended.
allowedboolean
True when a change is allowed now.
reasonstring or null
Why a change is not allowed. Null when it is.
validationRulesobject
The rules a new hostname must follow.
maxLengthCharsinteger
Maximum length in characters.
patternstring
Regular expression the hostname must match.
patternDescriptionstring
The pattern in words.
hostnameNormalizedboolean or null
Always false in this response, also when .local was added. Compare hostname with the name you sent.
serviceRecordSyncedboolean or null
True 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 | null
Always null. Reverse DNS is checked after the response is sent.
statusstring
not_changed, restored or partial_failure. One of not_changed, restored, partial_failure.
monitoredIpCountinteger
How many IP addresses were checked.
changesDetectedinteger
How many reverse DNS records changed.
restoredIpsarray of string
IP addresses whose reverse DNS was put back.
failedIpsarray of string
IP addresses whose reverse DNS could not be put back.
detailstring or null
A sentence about the result. Null when nothing changed.
updatedAtstring
When the change was made.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
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 vps_not_found.
409The VPS is still being set up. code is vps_not_ready. Retry after recovery.retryAfterSeconds.
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.