Skip to content

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.

https://api.hyperkub.com/v1

Every endpoint is under /v1.

Send an access key of type REST API as a bearer token:

Terminal window
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.

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:

Terminal window
# the second page of 50
curl "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.

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 name

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=100

A 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 clusters

Parameters 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.

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.

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.

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:

Terminal window
until [ "$(curl -sf "https://api.hyperkub.com/v1/clusters/$ID" \
-H "Authorization: Bearer $HYPERKUB_API_KEY" | jq -r .status)" = "running" ]; do
sleep 15
done

Every 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.

The reference is generated from the API itself. Download the document for client generators or your own tooling:

  • /openapi.yaml on this site
  • https://api.hyperkub.com/v1/openapi.json from the API, no key needed