Skip to content

Add a VPS to a placement group

POST /api/v2/placement-groups/{id}/members

Add a VPS to a placement group in set a, b or c. VPSes in different sets are kept on separate hardware. VPSes in the same set may share it. A VPS can be in one placement group at a time. GET /api/v2/placement-groups/candidates shows which VPSes can be added.

When the new member shares hardware with a VPS from another set, health becomes violation. Hostup then moves one of them to other hardware in the background. A running VPS keeps running during that move. Follow it with GET /api/v2/placement-groups/{id}/status. Returns the updated group.

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

Request

Path parameters

idstringrequired
The placement group ID (pg_…).

Body

vpsIdstringrequired
The VPS ID (vps_…) to add.
placementSetstring
The set to put the VPS in. Default a. One of a, b, c.

Example

POST /api/v2/placement-groups/{id}/members
curl -X POST "https://cloud.hostup.se/api/v2/placement-groups/pg_01hxa3b4c5d6e7f8g9h0j1k2m3/members" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m4",
"placementSet": "b"
}'

Responses

201 The updated placement group with the new member.

Response 201
{
"id": "pg_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "Production database",
"policy": "spread",
"health": "ok",
"needsAttention": false,
"compatibilityKey": null,
"members": [
{
"vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "db-primary",
"instanceUrl": "/instance/vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"placementSet": "a",
"status": "placed",
"addedAt": "2026-06-28T10:02:00.000Z"
},
{
"vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m4",
"name": "db-replica",
"instanceUrl": "/instance/vps_01hxa3b4c5d6e7f8g9h0j1k2m4",
"placementSet": "b",
"status": "placed",
"addedAt": "2026-06-28T10:05:00.000Z"
}
],
"actions": {
"canRename": {
"allowed": true,
"reason": null
},
"canDelete": {
"allowed": true,
"reason": null
},
"canAddMember": {
"allowed": true,
"reason": null
},
"canResolve": {
"allowed": false,
"reason": "not_needed"
}
},
"createdAt": "2026-06-28T10:00:00.000Z",
"updatedAt": "2026-06-28T10:05:00.000Z"
}
Response fields
idstring
The placement group ID (pg_…).
namestring
Name of the group.
policystring
Placement policy. Always spread. One of spread.
healthstring
ok: every set is apart. reconciling: a VPS is being moved. violation: VPSes from different sets share hardware. One of ok, reconciling, violation.
needsAttentionboolean
true when automatic separation could not finish. Check actions.canResolve.
compatibilityKeystring or nulldeprecated
Deprecated. Always null.
membersarray of object
VPSes in the group, oldest first.
vpsIdstring
The VPS ID (vps_…).
namestring
Hostname or label of the VPS.
instanceUrlstring
Path of the VPS page in the client area.
placementSetstring
The set the VPS belongs to. VPSes in different sets are kept on separate hardware. One of a, b, c.
statusstring
placed: on hardware no other set uses. migrating: being moved. colocated: shares hardware with a VPS from another set. unknown: its location could not be read. One of placed, migrating, colocated, unknown.
addedAtstring
When the VPS joined the group.
actionsobject
canRenameobject
Whether the group can be renamed.
allowedboolean
reasonstring or null
Why the action is not allowed. null when it is.
canDeleteobject
Whether the group can be deleted.
allowedboolean
reasonstring or null
Why the action is not allowed. null when it is.
canAddMemberobject
Whether a VPS can be added.
allowedboolean
reasonstring or null
Why the action is not allowed. null when it is.
canResolveobject
Whether POST /api/v2/placement-groups/{id}/actions/resolve can separate the group now.
allowedboolean
reasonstring or null
not_needed: nothing to fix with a restart. no_restart_target: no separate hardware is free right now. null when allowed is true. One of not_needed, no_restart_target.
createdAtstring
When the group was created.
updatedAtstring
When the group was last changed.

Errors

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

400The request is not valid. invalid_request: vpsId is not a VPS ID or placementSet is not a, b or c. An unknown field in the body also returns it. not_a_vps: the service is not a VPS.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404placement_group_not_found: no such group in your account. vps_not_found: no such VPS in your account.
409The VPS cannot join. already_grouped: it is in a placement group already. Remove it there first. server_not_eligible: it cannot be placed right now.
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.