Skip to main content

API documentation

Planeon exposes a REST API alongside the web console; the web console itself is just one client of it. The OpenAPI 3.1 document is the source of truth for every request and response shape.

OpenAPI document​

The API serves its own OpenAPI document at:

GET /openapi.yaml

Interactive documentation​

Browsable, interactive API documentation (Scalar) is served by the API service itself at:

GET /docs

Use it to explore every endpoint and schema and try requests directly against your own instance — it always reflects exactly the contract your running version serves.

Authentication​

API calls authenticate the same way the web console does: with an OIDC access token from your identity provider, sent as a bearer token:

Authorization: Bearer <access-token>

Get a token from your identity provider the same way the web console does — an OAuth2/OIDC flow against the issuer and client configured for your Planeon instance (see Identity providers). Planeon validates the token's issuer, audience, signature, and expiry on every request; it never issues or stores its own API keys or passwords.

GET /openapi.yaml, GET /docs, and the health/readiness endpoints (/healthz, /readyz) are public and need no token.

Permissions​

Every API operation enforces the same permission model as the web console — there's no separate API-only access level. Read operations require the resource's :read permission (for example pools:read), and operations that create, change, or delete something require the matching :manage permission (pools:manage); platform:admin overrides every check. See Access management → Built-in permissions for the full permission list and how to grant them to a user or group.