Skip to content
Portal

API Reference

The Pilvio.pro REST API provides programmatic access to platform features and backs the portal itself. It uses JSON for request and response bodies.

Base URL

All API calls use HTTPS, on your portal's own domain:

https://app.pilvio.pro/api/1

Authentication

The API uses Bearer token (JWT) authentication — there is no username/password grant on the API itself.

Getting a JWT

  1. Click APIs in the left navigation drawer (between Docs and IAM).
  2. The page is headed RESTful API and has the buttons EXPLORE API and CREATE JWT. Click CREATE JWT.
  3. In the dialog, use Select customer under "Choose the customer this JWT gives access to". CREATE JWT stays disabled until a customer is chosen.
  4. Optionally switch on Refreshable (off by default) and enter a Refresh token name.
  5. Click CREATE JWT (or CANCEL). Creating a JWT needs the IAM owner scope; if you lack it, the Authorization Required dialog appears first.

The APIs page also lists your existing refresh tokens in the Existing refresh tokens table (Name, Created, Last used and Actions), where each token can be revoked with Revoke.

For automated, non-interactive access, see Service Accounts, which generates its own short-lived JWTs scoped to whatever roles are attached to the service account.

Using the Token

Include the token in the Authorization header of every request:

GET /api/1/customers/{customer_id}/cloudspaces HTTP/1.1
Host: app.pilvio.pro
Authorization: bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Tip

Tokens expire. If a request starts failing with an authentication error, get a fresh JWT from the APIs page and retry.

Request & Response Format

Requests and responses use JSON.

Pagination

List endpoints use cursor-based pagination with limit and start_after query parameters (not page numbers):

GET /api/1/customers/{customer_id}/cloudspaces?limit=50&start_after=<cursor>

Resource Scoping

Nearly every endpoint is scoped under a customer, and most are scoped under a further resource within that customer — for example:

/customers/{customer_id}/cloudspaces
/customers/{customer_id}/cloudspaces/{cloudspace_id}/vms
/customers/{customer_id}/cloudspaces/{cloudspace_id}/vms/{vm_id}

The full path structure for every resource is easiest to browse directly in the interactive reference below, grouped by tag (customers, admin, locations, utilities, me, and alpha for newer, subject-to-change endpoints).

Interactive API Documentation

The full OpenAPI (Swagger) specification is browsable directly:

  1. Click APIs in the left navigation drawer (between Docs and IAM).
  2. Click EXPLORE API.

This opens the interactive Swagger UI at app.pilvio.pro/api/1, where you can browse every endpoint by tag and try requests directly from the browser. Click Authorize and paste in your JWT to make authenticated calls from the explorer itself.

Note

The API is explicitly marked v1.0Beta and "incomplete and may have changes" in its own specification — expect some endpoints to change as the platform evolves.

SDKs & CLI

For common tasks, consider using the app-pilvio-pro CLI instead of the raw API. The CLI handles JWT configuration and formats output for scripting. See the CLI User Guide and Downloads.