Using the API

The Hyperkub API is a REST API over JSON. Everything the control plane can do is available over it.

The full endpoint listing, with request/response schemas and a built-in request console, is in the API Reference. This page covers the conventions that apply everywhere.

Note

This API manages your clusters — creating them, scaling pools, billing. To manage what runs inside a cluster, use the Kubernetes API with a cluster credential.

Base URL

https://api.hyperkub.com

Every endpoint is versioned under /v1.

Authentication

Pass an API key in the X-Tess-Token header. Create keys in the control plane under Account → API keys.

curl https://api.hyperkub.com/v1/clusters \
  -H "X-Tess-Token: $HYPERKUB_TOKEN"

A missing, invalid or expired token returns 401.

Caution

An API key carries the permissions of the account it belongs to. Store it in a secret manager, never in source control, and issue a separate key per integration so you can revoke one without breaking the others.

Pagination

Every endpoint that returns a collection takes the same three parameters:

Parameter	Meaning	Default
offset	Rows to skip. Minimum 0.	0
limit	Page size. Clamped to 1–100.	100
sort	Comma-separated field names.	unset

and returns the same envelope:

{
  "data": [],
  "total": 237,
  "offset": 0,
  "limit": 100
}

total counts every row matching your filters, ignoring pagination. Use it to decide whether another page exists — do not rely on a short data array:

# second page of 50
curl "https://api.hyperkub.com/v1/clusters?offset=50&limit=50" \
  -H "X-Tess-Token: $HYPERKUB_TOKEN"

Note

limit is clamped server-side. Asking for limit=1000 yields 100, not an error — always read limit back from the response.

Sorting

sort takes field names separated by commas. Prefix a field with - for descending or + for ascending; plain names sort ascending.

?sort=-created_at         newest first
?sort=name                by name, A→Z
?sort=-created_at,name    newest first, ties broken by name

Filtering

Filters vary by endpoint and are documented per endpoint in the reference. Most collections accept account_id.

Fields backed by a fixed set of values also support negation with !:

?status=running     only running clusters
?status=!error      everything except errored clusters

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 for humans and may change without notice.

Status	Meaning
400	Malformed request or failed validation.
401	Missing, invalid or expired token.
403	Authenticated, but not allowed to do this.
404	No such resource, or you cannot see it.
500	Something broke on our side. Safe to retry.

Asynchronous operations

Provisioning is not instant. Endpoints that create or resize infrastructure return immediately with a status such as provisioning, and the work completes in the background.

Poll the resource until its status settles:

until [ "$(curl -sf "https://api.hyperkub.com/v1/clusters/$ID" \
  -H "X-Tess-Token: $HYPERKUB_TOKEN" | jq -r .status)" = "running" ]; do
  sleep 10
done

Back off between polls rather than polling in a tight loop.