Skip to content

Get the hostname of a VPS

GET /api/v2/vps/{id}/hostname

Returns the hostname of a VPS, whether it can be changed now and the rules a new hostname must follow. Change it with PUT /api/v2/vps/{id}/hostname. A VPS that is still being set up returns 409 vps_not_ready.

Authentication: An API key with the scope read:vm. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

GET /api/v2/vps/{id}/hostname
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/hostname" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The hostname and its change gate.

Response 200
{
"hostname": "web-01.example.com",
"reloadRecommended": false,
"accountInactive": false,
"accountStatus": null,
"cacheCleared": false,
"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."
}
}
Response fields
hostnamestring or null
The hostname of the VPS. Null when the VPS service has ended.
reloadRecommendedboolean
True when the VPS service has ended and its cached data was cleared during this call. Read the VPS list again.
accountInactiveboolean
True when the VPS service has ended (terminated or cancelled).
accountStatusstring or null
The service status when accountInactive is true, for example terminated. Otherwise null.
cacheClearedboolean
True when cached data for the VPS was cleared during this call. This happens when the service has ended.
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.

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.