REST API¶

cloudalone serves an hcloud-compatible REST surface under /v1. The wire format is checked against the real hcloud Python client, and the request/response/action-polling behaviour is audited against the Go CLI. This page lists the implemented surface; for full field semantics, the Hetzner Cloud API docs are the reference cloudalone tracks.

Authentication¶

Every route requires a bearer token:

Authorization: Bearer <token>

Missing or wrong tokens get 401 with the error envelope below. The comparison is constant-time.

Endpoints¶

Servers¶

Method	Path	Notes
`GET`	`/v1/servers`	filters: `name`, `status`, `label_selector` (accepted)
`POST`	`/v1/servers`	returns `201` + an action; boots in the background
`GET`	`/v1/servers/{id}`
`DELETE`	`/v1/servers/{id}`	returns an action

Server actions¶

Method	Path	Notes
`GET`	`/v1/servers/{id}/actions`	filters: `id`, `status`, `sort`
`POST`	`/v1/servers/{id}/actions/{action}`	`action` ∈ `poweron`, `poweroff`, `reset`, `shutdown`, `reboot`, `rebuild`

Actions¶

Method	Path	Notes
`GET`	`/v1/actions`	filters: `id`, `status`; the CLI polls here
`GET`	`/v1/actions/{id}`

SSH keys¶

Method	Path
`GET` / `POST`	`/v1/ssh_keys`
`GET` / `DELETE`	`/v1/ssh_keys/{id}`

Catalog (read-only)¶

GET /v1/images, /v1/server_types, /v1/locations, /v1/datacenters: each also with a /{id} variant and a name filter.

The Actions model¶

Mutating calls return an action with a status of running, success, or error. The client polls GET /v1/actions?id=<id> until it settles. See How it works.

Error envelope¶

Errors use hcloud's shape:

{ "error": { "code": "not_found", "message": "server not found" } }

Status	`code`	When
`400` / `422`	`invalid_input`	malformed body or bad field
`401`	`unauthorized`	missing/wrong token
`404`	`not_found`	unknown server / key / catalog id
`409`	conflict	e.g. server name already in use

Not implemented¶

Networks, volumes, floating IPs, load balancers, firewalls, placement groups, and IPv4 for guests. Pagination is a stub (next_page is always null), and start_after_create / per-server action locks are post-0.1.