API: Groups

Generated from openapi.json 0.1.0-draft (draft)

Scaling groups: the current node inventory and the deploy lock.

List the current nodes of a group

get/groups/{groupId}/nodes

Inventory API. Returns the group's current nodes with phase, IP addresses, class, release and build id, so pipelines and tools such as Kamal or Ansible build their host lists from it instead of parsing events. Nodes whose build id differs from the group's current release are stale and can be rolling-replaced.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier, a ULID prefixed with `grp_`. Example: `grp_01J8X4V9K2N7Q3R5S6T7V8W9XB`.

* required

Responses

200: The group and its current nodes.
401: The API token is missing, invalid or revoked.
404: The group or node does not exist or belongs to another organisation.
422: The request body failed validation.
429: The organisation's API rate limit is exhausted; retry later.

Field	Type	Description
group*	Group
nodes*	array of Node	Every node the group currently tracks, in any phase.

Example

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

Hold a deploy lock on a group

post/groups/{groupId}/lock

Deploy lock. Pauses scaling actions while the customer's own rollout runs, so a scale-out cannot race a fleet-wide deploy. The lock expires by TTL, so a crashed pipeline cannot freeze a group forever. Whether healing of a dead node runs while a lock is held is not yet decided.

Parameters

Parameter	Type	Description
groupId (path)*	string	Group identifier, a ULID prefixed with `grp_`. Example: `grp_01J8X4V9K2N7Q3R5S6T7V8W9XB`.

* required

Request body

Field	Type	Description
ttl*	integer	Seconds after which the lock expires on its own.
reason*	string	Why the lock is held; shown in the group's event timeline.

* required

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

Responses

200: The lock is held until the returned time.
401: The API token is missing, invalid or revoked.
404: The group or node does not exist or belongs to another organisation.
422: The request body failed validation.
429: The organisation's API rate limit is exhausted; retry later.

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/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" }'