API reference

Public API of the Hetscale control plane: the groups and their projects, the node reports, the release pointer, the inventory API, the deploy lock, the in-place deploy report, the rollout and the Prometheus endpoint, plus the signed deliveries Hetscale sends to the customer's endpoints: the webhook adapter's deployment events and, on Pro, the integrations' timeline events, alerts and tests. Operations marked implemented are served under /v1 on api.hetscale.com; the others are planned and may still change. Eight operations are stable and marked x-hetscale-stability: stable: the ones a deploy pipeline calls to hold and release a group's deploy lock, create a release, list a group's nodes, report an in-place deploy, start a rollout, and report that the deploy to a new node succeeded or failed. Within /v1, what a pipeline sends them and reads from their answers is not removed, renamed or narrowed: the method, path and ability of each, the request fields and their bounds, the success statuses, the answer fields a pipeline uses (the lock's end; the release's id, version, ref and build id and the group's generation; each node's id, class, phase, IPv4 address, private address and release; the rollout's id and its count of older servers; the reported node's phase), the node phases, Retry-After, and the error body and its codes. Everything else in this document is a draft and may still change before it leaves draft.

Base URL: https://api.hetscale.com/v1. Every request and response body is JSON. The specification is the source of these pages; nothing here is written by hand. The file itself is openapi.json (OpenAPI 3.1.0, version 0.12.0-draft). It is a draft, except the operations marked stable, so the rest may still change. Import it into an API client or a code generator.

Authentication

Authorization: Bearer <token> on every request. An organisation's API token from the panel's API tokens page, sent as Authorization: Bearer <id>|<secret>. A token acts for the member who created it and stops working when that member leaves the organisation. It may do only what its abilities allow: nodes:report, releases:write, groups:lock, nodes:read, rollouts:write, metrics:read, groups:read and groups:write. An ability counts only while the member's role holds it: reads for every member, the node reports, releases, the deploy lock and the rollout for an operator, a group's changes for an admin; an ability above the role is answered 403 forbidden.Tokens are never sent in a URL. A token is shown once, when you make it on the API tokens page, and expires after 30, 90 or 365 days, or never; 90 is the default. Each organisation may send 60 requests a minute. A request may carry an Idempotency-Key header: a retry by the same token with the same key and the same request within 24 hours gets the first answer again.

Endpoints

Groups · Projects · Nodes · Releases · Metrics · Webhooks

Errors

Errors return the Error schema:400 when an Idempotency-Key is malformed, 401 when the token is missing or invalid, 403 when it lacks the ability the operation needs or when the role of the member who made the token no longer holds that ability (Team's roles),404 when the group or node is not in your organisation, 409 when a report changes nothing, a request of the same token with the same key is still being handled, the group is not Live or paused for a release or the deploy lock (not Live for a rollout), a rollout already runs or has nothing to replace, or an in-place report names a server that is not a serving managed server of a webhook group, 422 when the body fails validation, names a release the group does not have, or reuses an Idempotency-Key with a different request or from another token, 429 when the rate limit is exceeded, and502 or 503 when Hetzner fails while a release is read back from your project; a 503 may be retried.

Schemas