Platform API
Where the platform's HTTP API lives, how its routes are organised, and how to list the routes an installation serves.
Everything the portal and the stsh CLI do goes through one HTTP API, at https://api.example.com.
You can call it yourself — from scripts, pipelines or your own tools — with the same permissions
you have in the portal.
One address for every module
The API is served at the root of its host; there is no /api prefix and no version segment in
the path. The platform's core answers its own routes and forwards every other request, unchanged,
to the installed module that registered the route. The routes you can call therefore depend on
which modules your installation has.
When a module is installed but not running, its routes answer 503 with the code
MODULE_UNAVAILABLE; retry shortly. A 503 with another code has another cause, and the code
decides whether retrying helps — see Errors.
How routes are organised
Routes follow the scopes that permissions are granted at:
| Scope | Route prefix |
|---|---|
| Platform | no boundary in the path, for example /clusters |
| Boundary | /boundaries/{boundaryId}/… |
| Resource group | /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/… |
| Resource | /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/resources/{type}/{name} |
Every call is checked against your roles at the scope its path names. When a route without a boundary in its path needs a permission, it is checked at the platform root, where only platform roles apply.
List the routes
Three endpoints describe the API. None of them needs a sign-in.
| Endpoint | What it gives you |
|---|---|
https://api.example.com/api/routes |
Every route of the core and of each installed module: path pattern, methods and the module that serves it |
https://api.example.com/api/routes/openapi.json |
The same list as an OpenAPI document — paths and methods only, without parameters, request bodies or response schemas |
https://api.example.com/swagger |
An interactive reference. It describes the core's own endpoints and includes the route list above |
/swagger is on unless an operator has turned it off (Swagger__Enabled=false); the two
route lists are always available.
Calling the API
Every call that reads or changes platform state needs a bearer token — see Authenticate. Requests and responses are JSON. When a call fails, the response carries an error body described in Errors.
Work that takes a while — creating, changing or deleting a resource — is recorded as an operation you can follow; see Operations.
With the CLI signed in, stsh api calls any route with your credentials:
stsh api GET /boundaries
stsh api GET /boundaries/<boundary-id>/resourcegroups-d '<json>' or -d @file.json sends a request body.
The portal also receives live updates over WebSocket connections under /hubs. They are an
internal interface of the portal and can change without notice; poll the API instead.