Manage node groups through the API

To manage node groups through the API, a token lists and reads them, exports a node group as one JSON document, changes its settings, starts observing a load balancer, and archives and restores. The API is on every plan.

Which token do I need?

A token made on the panel’s API tokens page acts for the member who made it, with that member’s rights.

• Read groups (groups:read) lists and reads.
• Change groups (groups:write) starts observing, changes settings, archives and restores.

How do I read a node group?

• GET /v1/projects lists the organisation’s projects with their prj_ ids.
• GET /v1/groups lists the node groups outside the Archive; ?archived=true lists the Archive.
• GET /v1/groups/{id} returns one node group as a single document: its identity, state, capacity, settings, template, deployment and schedules.

A webhook secret, the template’s user data and any token never appear in the document.

How do I export a node group as JSON?

On the panel, Export JSON in the More menu (⋯) of a node group’s Overview downloads the same document as <name>.json, so it can be kept in Git. The document’s settings block can be sent back unchanged with PATCH, and then nothing changes. Export settings, beside Export JSON, downloads only the settings block, as <name>-settings.json. It changes only when a setting does, so it suits a copy kept in Git, and sent back as the body of PATCH /v1/groups/{id} it changes nothing.

How do I change its settings?

PATCH /v1/groups/{id} takes any part of the settings block:

• min and max;
• the policy: a named preset, custom with its rules, or target with a metric and a value (target tracking);
• the drain window, the readiness deadline and how long a failed server is kept (drain_window_seconds, readiness_deadline_seconds, keep_failed_nodes_seconds);
• the euro ceiling and the release-age warning (euro_ceiling, release_age_warning_days);
• the out-of-stock fallback, the spreading over hosts and the SSH keys of new servers (fallback, placement, ssh_key_ids);
• keeping servers while the type is out of stock (hold_scale_in_while_sold_out, Can a scale-in wait while my type is out of stock?);
• the decision mode, automatic or propose (decision_mode).

A field left out keeps its value. A field the body does not have is refused, not ignored: the answer is 422 validation_failed, with the field listed under its dotted path, so send the document’s settings block or a part of it, never the whole document. Only Live and paused node groups can be changed. The change is all or nothing: if one part is refused, nothing is written. A named preset sets every other policy field: naming the group’s own preset keeps the values it took, and naming another takes that preset’s values today. Send "preset": "custom" to change them one by one. The timeline names the token that made the change.

How do I edit safely?

Every read of a node group carries an ETag. Send it back in If-Match: if a setting changed since the read, on the panel or through another token, the answer is 412 precondition_failed and nothing is written. Without If-Match the last write wins, as on the panel.

Read the node group, keeping its document and its ETag:

ETAG=$(curl -sS https://api.hetscale.com/v1/groups/grp_… \
  -H "Authorization: Bearer $HETSCALE_TOKEN" -o group.json -D - \
  | tr -d '\r' | sed -n 's/^[Ee][Tt][Aa][Gg]: //p')

Then change one setting, only if nothing changed meanwhile:

curl -sS -X PATCH https://api.hetscale.com/v1/groups/grp_… \
  -H "Authorization: Bearer $HETSCALE_TOKEN" -H 'Content-Type: application/json' \
  -H "If-Match: $ETAG" -d '{"max": 5}'

The answer is the new document with its new ETag.

How do I start observing through the API?

POST /v1/groups takes:

• the project’s id;
• the Hetzner ids of the load balancer and the seed server;
• a name and an optional server prefix;
• the same questions as the panel, under answers.

The project must have been read on the panel first. A setup Hetscale cannot scale, or that has nothing to observe yet, is refused with the panel’s reasons. A load balancer gets one trial ever, and the trial lasts 14 days. The day-0 report follows in the background, and the node group’s document shows how far it has come.

How do I archive and restore a node group?

DELETE /v1/groups/{id} archives a node group, and POST /v1/groups/{id}/restore brings it back: an observing or paused node group as it was, a Live one paused. Archiving is refused while servers Hetscale created still run in it (lower its capacity first) or during a Rehearsal. Nothing is ever deleted: Archive and restore.

What stays on the panel?

• Connecting a project and its token.
• The path to Live: the Read & Write token, delete protection, the Rehearsal, the seed’s promotion.
• Schedules, the adapter and its webhook URL.
• Pause, resume, the emergency stop, maintenance.
• A manual desired capacity, and approving proposals.

The API reference lists every field of the document and every answer.