API reference

Generated from openapi.json 0.1.0-draft (draft)

Public API of the Hetscale control plane: the inventory API, the deploy lock, the release pointer and the optional node callbacks, plus the signed events Hetscale sends to the customer's webhook endpoint. This file is written by hand from ADR-0014 (webhook adapter contract) and ADR-0020 (release model, deploy lock and inventory API), as decided in ADR-0039, so the reference can be published before the routes exist. It is replaced by generated output once the routes are implemented; the generator must reproduce it.

Base URL: https://api.hetscale.com. Every request and response body is JSON. The specification is the source of these pages; nothing here is written by hand.

Authentication

Authorization: Bearer <token> on every request: Sanctum API token of the organisation. Tokens belong to the organisation and are never sent in a URL.

Endpoints

get /groups/{groupId}/nodes	List the current nodes of a group
post /groups/{groupId}/lock	Hold a deploy lock on a group
post /nodes/{nodeId}/ready	Report that a node has been deployed
post /nodes/{nodeId}/failed	Report that the deploy to a node failed
post /groups/{groupId}/releases	Create a release and move the group's current pointer to it
webhook node.created	A new node is booted and reachable
webhook node.terminating	A node is leaving the group
webhook group.release_changed	The group's current release changed

Groups · Nodes · Releases · Webhooks

Errors

Errors return the Error schema:401 when the token is missing or invalid, 404 when the group or node is not in your organisation, 422 when the body fails validation, 429when the rate limit is exceeded.

Schemas

Group

Field	Type	Description
id*	string	Group identifier, a ULID prefixed with `grp_`.
name*	string	Name of the group as shown in the panel.
generation*	integer	Counter incremented on every template or release change; a scaling decision made against an older generation is discarded.

* required

Node

Field	Type	Description
id*	string	Node identifier, a ULID prefixed with `node_`.
server_id*	integer	Id of the server in the customer's Hetzner Cloud project.
name*	string	Server name in Hetzner Cloud, `hetscale-<group>-<ulid>`.
class*	`adopted` · `managed`	`adopted` is the seed server the customer already ran, which is never scaled in or replaced; `managed` nodes were created by Hetscale and have the full lifecycle.
phase*	`REQUESTED` · `PROVISIONING` · `BOOTING` · `DEPLOYING` · `HEALTH_CHECKING` · `ACTIVE` · `DRAINING` · `TERMINATING` · `TERMINATED` · `PROVISION_FAILED` · `DEPLOY_FAILED` · `HEALTH_FAILED` · `DRAIN_TIMEOUT` · `TERMINATION_FAILED`	Current phase in the node lifecycle; only `ACTIVE` nodes receive traffic.
ipv4*	string \| null	Public IPv4 address, or null when the server has none.
ipv6*	string \| null	Public IPv6 address, or null when the server has none.
private_ip*	string \| null	Address in the group's private network, or null when the server is not attached to one.
location*	string	Hetzner Cloud location the server runs in, such as `nbg1`.
server_type*	string	Hetzner Cloud server type the server was created with, such as `cx23`.
release*	Release
build_id*	string \| null	Build identifier the node reports, or null before it has reported one; a value different from the current release's marks the node as stale.
phase_entered_at*	string (date-time)	When the node entered its current phase.

* required

Release

Field	Type	Description
id*	string	Release identifier, a ULID prefixed with `rel_`.
ref*	string	The artefact the release boots from: a Hetzner snapshot id, an image digest or a Coolify deployment reference.
build_id*	string \| null	The customer's own build identifier for the release, or null when none was given.
source*	`snapshot` · `image` · `coolify` · `api`	How the release was created: a snapshot of the seed, an image digest, a Coolify deployment or the releases endpoint.
created_at*	string (date-time)	When the release was recorded.

* required

Error

Field	Type	Description
message*	string	Human-readable description of the error.
errors	object	Validation messages keyed by field name; present on 422 responses only.

* required