API Reference¶

PteroCloud exposes a customer Client API, an admin Application API, an Agent API and an internal console-gateway API. This page documents the customer Client API in full and the other APIs at a high level. No API returns a secret.

Authentication and conventions¶

The Client API authenticates with a panel client API key (Authorization: Bearer <key>), scoped to the authenticated user.
The Application API requires an admin-scoped panel application API key.
The Agent API authenticates with the enrolled agent credential (not a user or API key).
Route-model binding uses UUIDs. Unknown or foreign resources answer 404 — existence is never leaked.
Requests may carry X-Request-Id; it is reused as the correlation id.
Provisioning accepts an Idempotency-Key. All timestamps are ISO 8601 UTC.
Every error response carries a customer-safe message, an error code and an opaque support id. Unknown errors map to PC-SYS-000 and never include a stack trace. See Error codes.

Client API (customer-facing)¶

Base path: /api/client/cloud
Auth: panel client API key, scoped to the authenticated user.
Scope: the caller's own instances and account-level resources (volumes, private networks, floating IPs, SSH keys). The Client API never exposes another tenant's resources, provider internals or credentials.

Instances¶

Method	Path	Purpose
`GET`	`/api/client/cloud`	List the caller's instances.
`POST`	`/api/client/cloud`	Create an instance (idempotent; rate-limited).
`GET`	`/api/client/cloud/{cloudInstance}`	Show one instance.
`DELETE`	`/api/client/cloud/{cloudInstance}`	Delete one instance.
`POST`	`/api/client/cloud/{cloudInstance}/power`	Power action (`start`, `stop`, `restart`, `kill`).
`POST`	`/api/client/cloud/{cloudInstance}/rebuild`	Rebuild from an image.
`GET`	`/api/client/cloud/{cloudInstance}/metrics`	Metrics series.
`GET`	`/api/client/cloud/{cloudInstance}/activity`	Activity log.
`GET`	`/api/client/cloud/{cloudInstance}/tasks`	Task history.
`GET`	`/api/client/cloud/{cloudInstance}/diagnostics`	Instance diagnostics.
`GET`	`/api/client/cloud/images`	Images available to the caller.

Console, SSH and settings¶

Method	Path	Purpose
`GET`	`/api/client/cloud/{cloudInstance}/console`	Console capabilities.
`POST`	`/api/client/cloud/{cloudInstance}/console/session`	Create a console session.
`POST`	`/api/client/cloud/{cloudInstance}/console/sessions/{sessionUuid}/revoke`	Revoke a console session.
`GET`	`/api/client/cloud/{cloudInstance}/ssh`	SSH connection info.
`PATCH`	`/api/client/cloud/{cloudInstance}/settings/rename`	Rename.
`PATCH`	`/api/client/cloud/{cloudInstance}/settings/hostname`	Change hostname.
`PATCH`	`/api/client/cloud/{cloudInstance}/settings/timezone`	Change timezone.
`GET`	`/api/client/cloud/{cloudInstance}/settings/password`	Show the initial password (show-once window).
`POST`	`/api/client/cloud/{cloudInstance}/settings/password`	Regenerate the password.
`GET`/`POST`/`PATCH`/`DELETE`	`/api/client/cloud/ssh-keys[/{keyUuid}]`	Manage SSH keys.

Network, storage, media and backups¶

Method	Path	Purpose
`GET`	`/api/client/cloud/{cloudInstance}/network`	Network overview.
`GET`/`POST`	`/api/client/cloud/{cloudInstance}/network/ips`	List / attach IPs.
`DELETE`	`/api/client/cloud/{cloudInstance}/network/ips/{cloudIpAddress}`	Detach an IP.
`POST`	`/api/client/cloud/{cloudInstance}/network/ips/{cloudIpAddress}/promote`	Promote to primary.
`PATCH`	`/api/client/cloud/{cloudInstance}/network/ips/{cloudIpAddress}/rdns`	Set reverse DNS.
`GET`	`/api/client/cloud/{cloudInstance}/bandwidth`	Bandwidth usage.
`GET`/`PUT`/`DELETE`	`/api/client/cloud/{cloudInstance}/firewall[/rules\|/enabled]`	Firewall rules and toggle.
`GET`/`POST`	`/api/client/cloud/{cloudInstance}/backups`	List / create backups.
`POST`	`/api/client/cloud/{cloudInstance}/backups/{cloudBackup}/restore`	Restore in place.
`POST`	`/api/client/cloud/{cloudInstance}/backups/{cloudBackup}/restore-new`	Restore as a new instance.
`POST`	`/api/client/cloud/{cloudInstance}/backups/{cloudBackup}/verify`	Verify.
`POST`	`/api/client/cloud/{cloudInstance}/backups/{cloudBackup}/protect`	Protect from retention.
`GET`/`POST`/`PATCH`/`DELETE`	`/api/client/cloud/{cloudInstance}/backup-schedules[/{backupPolicy}]`	Backup schedules.
`GET`/`POST`	`/api/client/cloud/{cloudInstance}/snapshots`	List / create snapshots.
`POST`/`DELETE`	`/api/client/cloud/{cloudInstance}/snapshots/{cloudSnapshot}[/restore]`	Restore / delete.
`GET`	`/api/client/cloud/{cloudInstance}/storage`	Storage overview.
`POST`	`/api/client/cloud/{cloudInstance}/storage/root/resize`	Grow the root disk.
`GET`/`POST`	`/api/client/cloud/volumes[/{cloudVolume}]`	Account volumes.
`POST`	`/api/client/cloud/volumes/{cloudVolume}/attach\|detach\|resize`	Volume lifecycle.
`GET`/`POST`	`/api/client/cloud/{cloudInstance}/media/iso[/mount\|/unmount\|/boot]`	ISO library.
`GET`/`POST`/`DELETE`	`/api/client/cloud/private-networks[/{cloudNetwork}]`	Private networks.
`POST`	`/api/client/cloud/private-networks/{cloudNetwork}/attach\|detach`	Attach/detach a NIC.
`GET`	`/api/client/cloud/floating-ips`	List floating IPs.
`POST`	`/api/client/cloud/floating-ips/{cloudIpAddress}/attach\|detach\|move`	Floating IP lifecycle.
`GET`/`POST`/`DELETE`	`/api/client/cloud/{cloudInstance}/schedules[/{scheduleUuid}]`	Scheduled actions.
`GET`/`POST`	`/api/client/cloud/{cloudInstance}/rescue[/enter\|/exit]`	Rescue mode.

Example¶

GET /api/client/cloud/9f1c2f2e-2b7a-4a1e-9f5b-2f6b6a3c1d20 HTTP/1.1
Host: panel.example.com
Authorization: Bearer ptlc_xxxxx
Accept: application/json

{
  "object": "cloud_instance",
  "attributes": {
    "uuid": "9f1c2f2e-2b7a-4a1e-9f5b-2f6b6a3c1d20",
    "name": "web-01",
    "hostname": "web-01.example.com",
    "status": "running",
    "cpu_cores": 2,
    "memory_mb": 4096,
    "disk_mb": 81920,
    "primary_ipv4": "203.0.113.10",
    "primary_ipv6": null,
    "virtualization": "kvm",
    "boot_order": ["disk", "iso"],
    "timezone": "UTC",
    "created_at": "2026-01-01T00:00:00+00:00",
    "updated_at": "2026-01-01T00:05:00+00:00"
  }
}

A request for another customer's instance answers 404 with the standard resource-not-found body.

Administration & agent APIs¶

These APIs are not part of the customer API and are never reachable with a customer key. They are documented at a high level only; no endpoint returns a secret, and provider credentials are write-only.

Application API (admin)¶

Base path: /api/application/pterocloud
Auth: admin-scoped panel application API key.
Scope: the full control plane.

Route groups include: overview; instances; hypervisors (including maintenance, enrollment-token and revoke-agent); providers (including test, sync and credential rotation); locations / plans / images; networks / ip-pools / floating-ips / rdns / firewall; storage / volumes / isos; console/sessions; tasks / reservations; and scheduler/dry-run.

A provider credential is write-only: it is accepted on the credential endpoint and never returned.

Agent API¶

Base path: /api/pterocloud/agent
Auth: the enrolled agent credential; enrollment exchanges a one-time, expiring token under a dedicated per-IP rate limit.
Endpoints: enroll, heartbeat, metrics, tasks/next, and the task lifecycle reports (started, progress, completed, failed).

Task event reports are idempotent on (task_id, sequence).

Console gateway internal API¶

Base path: /api/application/pterocloud/console/internal
Auth: a dedicated console-gateway service credential, distinct from customer and admin tokens.
Routes: validate, session-state, heartbeat, revocations.

This API is outside the normal application-api middleware and has its own rate limiter.