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
idstringrequiredThe placement group ID (
pg_…).Body
vpsIdstringrequiredThe VPS ID (
vps_…) to add.placementSetstringThe set to put the VPS in. Default
a. One of a, b, c.Example
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.
{ "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
idstringThe placement group ID (
pg_…).namestringName of the group.
policystringPlacement policy. Always
spread. One of spread.healthstringok: every set is apart. reconciling: a VPS is being moved. violation: VPSes from different sets share hardware. One of ok, reconciling, violation.needsAttentionbooleantrue when automatic separation could not finish. Check actions.canResolve.compatibilityKeystring or nulldeprecatedDeprecated. Always
null.membersarray of objectVPSes in the group, oldest first.
vpsIdstringThe VPS ID (
vps_…).namestringHostname or label of the VPS.
instanceUrlstringPath of the VPS page in the client area.
placementSetstringThe set the VPS belongs to. VPSes in different sets are kept on separate hardware. One of
a, b, c.statusstringplaced: 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.addedAtstringWhen the VPS joined the group.
actionsobjectcanRenameobjectWhether the group can be renamed.
allowedbooleanreasonstring or nullWhy the action is not allowed.
null when it is.canDeleteobjectWhether the group can be deleted.
allowedbooleanreasonstring or nullWhy the action is not allowed.
null when it is.canAddMemberobjectWhether a VPS can be added.
allowedbooleanreasonstring or nullWhy the action is not allowed.
null when it is.canResolveobjectWhether
POST /api/v2/placement-groups/{id}/actions/resolve can separate the group now.allowedbooleanreasonstring or nullnot_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.createdAtstringWhen the group was created.
updatedAtstringWhen the group was last changed.
Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The 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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | placement_group_not_found: no such group in your account. vps_not_found: no such VPS in your account. |
| 409 | The 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. |
| 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. |