Skip to content

Set display labels for a VPS

PUT /api/v2/vps/{id}/metadata

Sets your own labels for a VPS: a display name and a name for its operating system. They change what the client area shows, not the server itself. displayName also becomes the service name on future invoices. Send null or an empty string to remove it. The service name then goes back to the hostname. To relabel the operating system, send operatingSystemName together with operatingSystemSourceName. Set the source to operatingSystem.displayName from GET /api/v2/vps/{id}. Sending the same value for both removes the label. A rebuild removes the operating system label. A hostname change with PUT /api/v2/vps/{id}/hostname removes the display name.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

displayNamestring or null
Name to show for the VPS, at most 120 characters. null or an empty string removes it.
operatingSystemNamestring or null
Operating system name to show, at most 120 characters. null removes it.
operatingSystemSourceNamestring or null
The current operatingSystem.displayName of the VPS. Required with operatingSystemName.

Example

PUT /api/v2/vps/{id}/metadata
curl -X PUT "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/metadata" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"displayName": "Production DB"
}'

Responses

200 The labels were saved.

Response 200
{
"customerMetadata": {
"displayName": "Production DB",
"operatingSystemName": "Debian 13",
"operatingSystemSourceName": "Debian 12",
"updatedAt": "2026-11-02T10:00:00.000Z"
}
}
Response fields
customerMetadataobject
The labels now saved.
displayNamestring or null
The display name. Null when none is set.
operatingSystemNamestring or null
The operating system name shown. Null when none is set.
operatingSystemSourceNamestring or null
The operating system name the label replaces.
updatedAtstring or null
When the labels were last changed.

Errors

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

400The body is invalid. errors[].pointer names the field.
401Authentication is required.
403The key lacks write:vm or the VPS belongs to another account.
404The VPS was not found. code is vps_not_found.
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.