API: Groups

Generated from openapi.json 0.12.0-draft (draft)

Scaling groups: their documents and settings, the start of Observe, the Archive, the current node inventory, the deploy lock and the rollout of older servers.

List the organisation's groups

get/groups

With a token that has the groups:read ability. Every group outside the Archive, oldest first; archived=true lists the Archive instead. The list comes in a data wrapper, so paging can come later as an addition.

Parameters

Parameter	Type	Description
archived (query)	`true` · `false`	`true` lists the groups in the Archive.

Responses

200: The groups.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
422: The body failed validation (`validation_failed`), a value is one the group does not take (`capacity_out_of_bounds`, `settings_out_of_bounds`, `fallback_type_unfit`, `fallback_cap_too_low` with the euros `needed`, `ssh_key_unknown`), or the load balancer or the seed cannot be observed (`load_balancer_missing`, `seed_not_behind_load_balancer`, `seed_created_by_hetscale`, `seed_architecture_unknown`, `seed_outside_zone`), or Kubernetes manages the load balancer or the seed (`kubernetes_managed`: the balancer carries the cloud controller manager's label `hcloud-ccm/service-uid`, or the seed the Cluster Autoscaler's `hcloud/node-group`). Also `idempotency_key_reused`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
data*	array of GroupSummary

Example

curl -X GET https://api.hetscale.com/v1/groups \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Start observing a load balancer

post/groups

With a token that has the groups:write ability, as the panel's Observe setup does. The case answers are assessed against the project's latest read and kept as its onboarding case; then Hetscale reads the load balancer and the project's servers inside the request and creates the group in observe, with the seed and every other server behind the balancer adopted. A load balancer has one trial, ever. The day-0 report follows in the background; the group's document is its status. Going Live stays on the panel.

Parameters

Parameter	Type	Description
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

Request body

Body: CreateGroup

Responses

201: The new group in `observe`.
400: The Idempotency-Key header is not 1 to 255 visible ASCII characters (`idempotency_key_invalid`).
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
409: The group or the project is not in a state for this: `not_live`, `rehearsal_running`, `release_missing`, `already_archived`, `not_archived`, `rehearsing`, `servers_running`, `project_not_read`, `case_declined`, `case_not_yet`, `case_needs_load_balancer`, `connection_inactive`, `load_balancer_already_observed`, `load_balancer_archived`, `load_balancer_observed_elsewhere` or `seed_already_observed`. Also `idempotency_key_in_flight`.
422: The body failed validation (`validation_failed`), a value is one the group does not take (`capacity_out_of_bounds`, `settings_out_of_bounds`, `fallback_type_unfit`, `fallback_cap_too_low` with the euros `needed`, `ssh_key_unknown`), or the load balancer or the seed cannot be observed (`load_balancer_missing`, `seed_not_behind_load_balancer`, `seed_created_by_hetscale`, `seed_architecture_unknown`, `seed_outside_zone`), or Kubernetes manages the load balancer or the seed (`kubernetes_managed`: the balancer carries the cloud controller manager's label `hcloud-ccm/service-uid`, or the seed the Cluster Autoscaler's `hcloud/node-group`). Also `idempotency_key_reused`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.
503: Hetzner could not be asked just now (`provider_unavailable`), or Hetscale could not open the stored secrets: its key service did not answer (`key_service_unavailable`) or its master key is unavailable (`secrets_unavailable`); retry, after the seconds in `Retry-After` when it is sent.

Example

curl -X POST https://api.hetscale.com/v1/groups \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Read a group

get/groups/{groupId}

With a token that has the groups:read ability, of a member who sees the group, archived or not. The document is the group's JSON export: its settings block goes back unchanged as a PATCH body, and applying it to the same group changes nothing.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.

* required

Responses

200: The group's document.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Example

curl -X GET https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Change a group's settings

patch/groups/{groupId}

With a token that has the groups:write ability, of a member who may configure the group, which needs the organisation open for writes. Changes what the panel's Settings page changes, the SSH keys of new servers and the decision mode, in one transaction: when one part is refused, nothing is written. A field left out keeps its value. Live and paused groups only (not_live). The timeline records the change with the actor api_token and the token's name. With If-Match the change is written only while the settings still have that ETag.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.
If-Match (header)	string	The `ETag` of a read of the group; a setting changed since is answered 412 `precondition_failed`. Without it the last write wins, as on the panel.

* required

Request body

Body: GroupSettings

Responses

200: The group's document.
400: The Idempotency-Key header is not 1 to 255 visible ASCII characters (`idempotency_key_invalid`).
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
409: The group or the project is not in a state for this: `not_live`, `rehearsal_running`, `release_missing`, `already_archived`, `not_archived`, `rehearsing`, `servers_running`, `project_not_read`, `case_declined`, `case_not_yet`, `case_needs_load_balancer`, `connection_inactive`, `load_balancer_already_observed`, `load_balancer_archived`, `load_balancer_observed_elsewhere` or `seed_already_observed`. Also `idempotency_key_in_flight`.
412: A setting changed since the `ETag` sent in `If-Match` (`precondition_failed`); nothing was written.
422: The body failed validation (`validation_failed`), a value is one the group does not take (`capacity_out_of_bounds`, `settings_out_of_bounds`, `fallback_type_unfit`, `fallback_cap_too_low` with the euros `needed`, `ssh_key_unknown`), or the load balancer or the seed cannot be observed (`load_balancer_missing`, `seed_not_behind_load_balancer`, `seed_created_by_hetscale`, `seed_architecture_unknown`, `seed_outside_zone`), or Kubernetes manages the load balancer or the seed (`kubernetes_managed`: the balancer carries the cloud controller manager's label `hcloud-ccm/service-uid`, or the seed the Cluster Autoscaler's `hcloud/node-group`). Also `idempotency_key_reused`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Example

curl -X PATCH https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Archive a group

delete/groups/{groupId}

With a token that has the groups:write ability, of a member who sees the group. Puts it in the Archive; nothing is ever deleted, and its reports and timeline stay. Refused while a server Hetscale created is alive in a project it can still reach (servers_running), during a Rehearsal (rehearsing) and for a group in the Archive already (already_archived).

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Responses

200: The group's document.
400: The Idempotency-Key header is not 1 to 255 visible ASCII characters (`idempotency_key_invalid`).
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
409: The group or the project is not in a state for this: `not_live`, `rehearsal_running`, `release_missing`, `already_archived`, `not_archived`, `rehearsing`, `servers_running`, `project_not_read`, `case_declined`, `case_not_yet`, `case_needs_load_balancer`, `connection_inactive`, `load_balancer_already_observed`, `load_balancer_archived`, `load_balancer_observed_elsewhere` or `seed_already_observed`. Also `idempotency_key_in_flight`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Example

curl -X DELETE https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Bring a group back from the Archive

post/groups/{groupId}/restore

With a token that has the groups:write ability, of a member who sees the group. An observing or paused group comes back as it was, a Live one paused, since its servers may have changed while nothing read them. A group outside the Archive is answered not_archived.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Responses

200: The group's document.
400: The Idempotency-Key header is not 1 to 255 visible ASCII characters (`idempotency_key_invalid`).
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
409: The group or the project is not in a state for this: `not_live`, `rehearsal_running`, `release_missing`, `already_archived`, `not_archived`, `rehearsing`, `servers_running`, `project_not_read`, `case_declined`, `case_not_yet`, `case_needs_load_balancer`, `connection_inactive`, `load_balancer_already_observed`, `load_balancer_archived`, `load_balancer_observed_elsewhere` or `seed_already_observed`. Also `idempotency_key_in_flight`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Example

curl -X POST https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/restore \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

List the current nodes of a group

get/groups/{groupId}/nodesstable

Inventory API, with a token that has the nodes:read ability, of a member who sees the group. Returns the group and its current nodes with phase, IP addresses, class, release, build id and older, so pipelines and tools such as Kamal or Ansible build their host lists from it instead of parsing events. A node is older when it runs another release than the group's current one by ref and build id, or none, or a template version that differs in what changes a running server, or when it runs outside a placement group while the group spreads its servers across hosts; a rollout replaces it, except while the load balancer no longer lists it as a target: a server was started in its place, and it leaves first on a scale-in. phase=active keeps the nodes that serve.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
phase (query)	`active`	`active` keeps the nodes in the `ACTIVE` phase, the ones that serve.

* required

Responses

200: The group and its current nodes.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
422: The request body failed validation (`validation_failed`, with the messages per field), or its Idempotency-Key was sent with a different request or by another token (`idempotency_key_reused`).
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
group*	Group
nodes*	array of Node	Every node the group tracks and has not terminated, in any phase; with `phase=active` only the serving ones.

Example

curl -X GET https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/nodes \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Hold a deploy lock on a group

post/groups/{groupId}/lockstable

Deploy lock, with a token that has the groups:lock ability, of a member who may change the group. While it holds, Hetscale makes no scaling decision and creates no server for a scale-out, a rollout, the fallback way back or a capacity window, so a scale-out cannot race a fleet-wide deploy. A healing replacement is never held, and a server a decision before the lock released still leaves. The lock ends at locked_until on its own, so a crashed pipeline cannot freeze a group; a second call sets a new end. The group must be Live or paused.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Request body

Field	Type	Description
ttl*	integer	Seconds after which the lock ends on its own, from 60 to 7,200.Range 60–7,200
reason*	string	Why the lock is held; shown on the group's timeline and page.

* required

{
  "ttl": 600,
  "reason": "deploy build 4711 via GitHub Actions"
}

Responses

200: The lock is held until the returned time.
400: The Idempotency-Key header is not 1 to 255 visible ASCII characters (`idempotency_key_invalid`).
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
409: The group is not Live or paused (`not_live`). Also `idempotency_key_in_flight`.
422: The request body failed validation (`validation_failed`, with the messages per field), or its Idempotency-Key was sent with a different request or by another token (`idempotency_key_reused`).
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
locked_until*	string (date-time)	When the lock expires and scaling actions resume.
reason*	string	The reason given when the lock was taken.

Example

curl -X POST https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/lock \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 600, "reason": "deploy build 4711 via GitHub Actions" }'

Release a group's deploy lock

delete/groups/{groupId}/lockstable

With a token that has the groups:lock ability, of a member who may change the group. Releases the lock at once, so scaling decisions and rollouts go on; the answer is the same when no lock was held.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Responses

200: No lock is held now.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
locked_until*	null	Always null: the group holds no lock.
reason*	null	Always null.

Example

curl -X DELETE https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/lock \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Replace a group's older servers

post/groups/{groupId}/rolloutstable

With a token that has the rollouts:write ability, of a member who may change the group. Starts replacing the group's older servers one at a time, surge then remove: a server from the current release and template starts, and once the load balancer's health check passes, an older server leaves through the drain window. A replacement that fails stops the rollout. Under a deploy lock it waits. The group must be Live.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Responses

201: The rollout started.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
409: The group is not Live (`not_live`), a rollout already runs (`already_running`) or every server runs the current release and template (`nothing_to_replace`), leaving out a server the load balancer no longer lists as a target, which a rollout does not replace. Also `idempotency_key_in_flight`.
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
rollout*	object

Example

curl -X POST https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/rollout \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"

Stop replacing a group's older servers

delete/groups/{groupId}/rollout

With a token that has the rollouts:write ability, of a member who may change the group. Stops the running rollout; a replacement already under way finishes.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier: the group's ULID in lower case, prefixed with `grp_`. Read in either case. Example: `grp_01j8x4v9k2n7q3r5s6t7v8w9xb`.
Idempotency-Key (header)	string	Optional on every state-changing request: 1 to 255 visible ASCII characters, kept for 24 hours per organisation and bound to the token that first sent it. A retry by the same token with the same key and the same request (method, path, query string and exact body) gets the first answer again, marked `Idempotent-Replayed: true`, instead of a second effect. The same key with a different request, or from another token of the organisation, is answered 422 `idempotency_key_reused`; while the first request still runs, its own token gets 409 `idempotency_key_in_flight`. A request that failed validation or on the server leaves no answer behind, so its retry runs again. Example: `deploy-4711-node-01j8x4v9k2n7q3r5s6t7v8w9xc`.

* required

Responses

200: Whether a running rollout was stopped.
401: The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).
403: The token lacks the ability the operation needs (`forbidden`).
404: The group or node does not exist or belongs to another organisation (`not_found`).
429: The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Field	Type	Description
stopped*	boolean	False when no rollout ran.

Example

curl -X DELETE https://api.hetscale.com/v1/groups/grp_01j8x4v9k2n7q3r5s6t7v8w9xb/rollout \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"