Using the API

Everything the console does, it does over the same REST API — creating clusters, managing node pools, issuing kubeconfigs, reading billing. This page is the orientation: the shape of the API and the conventions that hold across every endpoint. The API reference then documents each endpoint in full, generated from the live schema.

Base URL and versioning

The API lives under the console host, and the stable surface is versioned with a /v1/ prefix:

https://console.paasbox.com/api/v1/

Requests and responses are JSON over HTTPS. A new major version would move to /v2/ rather than change /v1/ under you.

Authentication

Two ways in, depending on who’s calling:

• Session — the console authenticates you with a browser session. That’s the interactive path; you don’t do anything special.
• API key — for scripts, CI, and anything non-interactive. Create a key in the console (see Teams & API keys), then send it in the Authorization header.

Keys look like pbx_live_…, are shown once at creation, belong to a team member, and can be revoked at any time. Send it on every request:

curl -s -H "Authorization: Token $PAASBOX_API_KEY" \
  https://console.paasbox.com/api/v1/teams/<team>/clusters/

Keep the key as the durable secret and use it to fetch a fresh kubeconfig per run rather than storing long-lived cluster credentials.

Everything is scoped to a team

Resources belong to a team, not to a person, so the paths that own resources carry the team slug:

/api/v1/teams/{team_slug}/clusters/
/api/v1/teams/{team_slug}/clusters/{cluster}/node-pools/

Your key acts within the teams its owner is a member of. The Teams & API keys page covers roles and what a key is allowed to do; the activity log attributes every key-driven change back to a person.

Pagination

List endpoints are paginated 100 items at a time. Ask for a page with ?page=:

curl -s -H "Authorization: Token $PAASBOX_API_KEY" \
  "https://console.paasbox.com/api/v1/teams/<team>/clusters/?page=2"

The response wraps the items in a small envelope — count is the total, next and previous are page URLs (or null at the ends), and results holds the items:

{
  "count": 137,
  "next": "https://console.paasbox.com/api/v1/teams/acme/clusters/?page=3",
  "previous": "https://console.paasbox.com/api/v1/teams/acme/clusters/?page=1",
  "results": [ /* … */ ]
}

Status codes and errors

Standard HTTP semantics apply. The ones worth knowing:

Code	Meaning
200 / 201 / 204	Success — read, created, or deleted (no body).
202	Accepted — the work runs asynchronously (e.g. a cluster starting); poll the resource for status.
401 / 403	Not authenticated / not allowed — check the key and the caller’s role in the team.
402	A billing or spend limit is blocking the action — resolve it in the console, then retry.
404	No such resource, or it’s outside the teams your key can reach.
409	Conflict with the current state (e.g. a name already in use).
412 / 422	The request was understood but rejected — a precondition failed, or a field didn’t validate.

Error responses carry a JSON body describing what went wrong; treat the status code as the source of truth for how to react.

The full reference

The API reference lists every endpoint, parameter, request body, and response shape. It is generated from the running service’s schema, so it tracks the API as it ships.