Using the API
The Hyperkub API is a REST API over JSON for managing your clusters, node pools, nodes and domains. Every endpoint, with its parameters and request and response schemas, is in the API Reference. This page covers the conventions that apply to all of them.
Base URL
Section titled “Base URL”https://api.hyperkub.com/v1Every endpoint is under /v1.
Authentication
Section titled “Authentication”Send an access key of type REST API as a bearer token:
curl "https://api.hyperkub.com/v1/clusters?limit=20" \ -H "Authorization: Bearer $HYPERKUB_API_KEY"Create keys in the control plane under Settings → Access Keys. A key can only do what its permissions allow, in one account, optionally limited to some of its clusters. See Access keys for the permissions and how keys behave.
A missing, invalid, expired or revoked key returns 401. A valid key without
the permission an endpoint needs returns 403 — each endpoint in the reference
names the permission it requires.
Pagination
Section titled “Pagination”Every endpoint that returns a collection takes the same parameters:
| Parameter | Meaning |
|---|---|
limit |
Page size, 1–100. Defaults to 20; larger values are capped at 100. |
offset |
Items to skip. Defaults to 0. |
sort |
Comma-separated field names; see below. |
and returns the same envelope:
{ "data": [], "total": 237, "offset": 0, "limit": 100}total counts every item matching your filters, ignoring pagination. Use it to
decide whether another page exists rather than relying on a short data array:
# the second page of 50curl "https://api.hyperkub.com/v1/clusters?offset=50&limit=50" \ -H "Authorization: Bearer $HYPERKUB_API_KEY"limit in the response is the page size actually used, so read it back.
Sorting
Section titled “Sorting”sort takes field names separated by commas. Prefix a field with - for
descending or + for ascending; a plain name sorts ascending.
?sort=-created_at newest first?sort=name by name, A→Z?sort=-created_at,name newest first, ties broken by nameFiltering
Section titled “Filtering”Filters differ per endpoint and are listed in the reference. Most
collections under a cluster take cluster_id:
GET /v1/cluster_pools?cluster_id=01j…&limit=100A filter over a fixed set of values, such as status, takes several values
separated by commas, and a value prefixed with ! excludes it:
?status=running only running clusters?status=!error everything except errored clustersParameters are strict: one an endpoint does not know is refused with 400
rather than ignored, so a typo shows up instead of silently returning
everything.
Errors
Section titled “Errors”Failures return a JSON body:
{ "status": 404, "error": "resource_not_found", "message": "cluster not found"}Branch on error, which is stable and machine-readable. message is written
to be read by a person and may change.
| Status | Meaning |
|---|---|
400 |
Malformed request, an unknown parameter, or failed validation. |
401 |
Missing, invalid, expired or revoked key. |
403 |
The key lacks the permission this endpoint needs. |
404 |
No such resource, or the key cannot reach it — for instance a cluster outside its cluster limit. |
405 |
The path exists, but not with this method. |
429 |
Too many requests for this key. Wait for the number of seconds in Retry-After. |
500, 502 |
Something failed on our side. Safe to retry with a backoff. |
Rate limits
Section titled “Rate limits”Requests are counted per key. Over the limit, the API answers 429 with a
Retry-After header giving the seconds until you can send again. Back off
rather than spreading requests over several keys.
Asynchronous operations
Section titled “Asynchronous operations”Creating, resizing, upgrading and deleting infrastructure takes minutes. These
requests return as soon as the work is accepted — with the resource in a status
such as provisioning, or 204 No Content — and the work continues in the
background.
Follow the resource’s status until it settles, backing off between polls:
until [ "$(curl -sf "https://api.hyperkub.com/v1/clusters/$ID" \ -H "Authorization: Bearer $HYPERKUB_API_KEY" | jq -r .status)" = "running" ]; do sleep 15doneEvery change also appears in the account’s activity
(GET /v1/events?parent=none&sort=-created_at&limit=20), attributed to the
key that made it.
OpenAPI document
Section titled “OpenAPI document”The reference is generated from the API itself. Download the document for client generators or your own tooling:
/openapi.yamlon this sitehttps://api.hyperkub.com/v1/openapi.jsonfrom the API, no key needed