Client API: Cloud Compute

Cloud Compute VM instances (power, console, backups, and details). Paths remain under /api/v1/client/vps.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

GET /api/v1/client/vps

List all VPS instances owned by the current user.

Each row carries ipv6_address and ipv6_prefix, null until the instance has IPv6.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/templates

OS templates ready for order/rebuild: enabled and ready on at least one active node.

ready_nodes counts those hosts across the fleet. Pass uuid to learn which templates a rebuild of that instance accepts.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}

Get VPS instance details including template metadata.

ipv6_address is the address the guest holds in its IPv6 /64 and ipv6_prefix the /64 itself; both are null until the instance has IPv6.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/backups

List backups for this instance.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/backups

Create a new backup of this instance.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json

GET /api/v1/client/vps/{uuid}/backups/automatic

The instance's automatic backups, for its Backups tab.

{available, frequency, keep, latest_backup_at, next_run_at, last_run_at, last_error, automatic_backup_ids, backups, service_id}: available is whether its automatic backups add-on is on, frequency weekly or daily, keep how many automatic backups it keeps, and backups every backup being taken or kept, newest first, each with its origin (auto or manual). Platform only: a brand sells its own catalogue.

Authentication: an access token, sent as Authorization: Bearer <token>.

DELETE /api/v1/client/vps/{uuid}/backups/{backup_id}

Delete a backup.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/backups/{backup_id}/restore

Restore from a backup. This will restart the VPS.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/bandwidth

Get current billing period bandwidth usage vs plan traffic allotment (TB).

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/cloud-init/regenerate

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/config

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/console

Start a display console session on the instance's host.

Answers vnc_ws (the websocket path), vnc_session (its session query parameter), vnc_password (the VNC password) and expires_in, the seconds left to connect; ask again for every connection. display is vga when the console shows the instance's screen, serial while the instance still uses its serial port as its screen, and pending while it waits for the display adapter its image now uses. One restart with the reboot power action ends either of the last two; a reboot inside the instance does not. Another account's instance answers 404, and a host that cannot start a console answers 400 with a message that starts Console unavailable.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/credentials

Username + whether a password is stored (no plaintext).

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/graphs

Get RRD graph data from Proxmox.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/guest

Authentication: an access token, sent as Authorization: Bearer <token>.

PATCH /api/v1/client/vps/{uuid}/hostname

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/vps/{uuid}/images

Turn this stopped instance into a disk image (app/modules/vps/custom_images/capture.py).

409 while the instance runs, and on a host that cannot export a disk. The image is pending until its disk is copied and checked.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/client/vps/{uuid}/ips

The addresses attached to the instance, primary first.

Each row has version (ipv4 or ipv6) and kind: routed for the instance's own IPv6 /64 (address is the network, prefix_len 64), block for a subnet or one of its hosts, else standalone for a floating address.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/ipv6

Give the instance its IPv6: a /64 routed to it, at no charge.

Answers {prefix, address, reboot_required}: the /64, the address the guest takes in it (the network's ::1, with fe80::1 as its gateway), and whether you need to restart the instance for the guest to take it. Asking again answers the /64 the instance already has, with reboot_required false. A new instance gets its /64 when it is created in a location with IPv6; this adds one to an instance that has none.

Answers 409 when the location has no IPv6 yet or none left, or while the instance is migrating; 404 when the instance is not yours; 429 when you ask too often.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/name

Give the instance a name in a zone the customer holds: A and AAAA records for its addresses, optionally the same name as reverse DNS and as the guest hostname.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/vps/{uuid}/power

Execute a power action on the VPS.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/client/vps/{uuid}/ptr

Reverse DNS of every address attached to the instance.

The instance's IPv6 /64 is listed as the address its guest holds.

Authentication: an access token, sent as Authorization: Bearer <token>.

PATCH /api/v1/client/vps/{uuid}/ptr

Set the reverse DNS of one attached address (the primary by default).

address may be any address inside the instance's IPv6 /64.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/vps/{uuid}/rebuild

Rebuild the VPS with a new OS template. This destroys all data.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/vps/{uuid}/rescue/enter

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/vps/{uuid}/rescue/exit

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/rescue/media

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/reset-password

Reset the root/admin password. Requires QEMU guest agent.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/resize-preview

Capacity/mode preview for a plan change resize (billing via /services change-plan).

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/client/vps/{uuid}/snapshots

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/snapshots

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

DELETE /api/v1/client/vps/{uuid}/snapshots/{snapshot_id}

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/vps/{uuid}/snapshots/{snapshot_id}/rollback

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/ssh-keys

The public keys on the instance, so a PUT can start from them: the PUT replaces them all.

Authentication: an access token, sent as Authorization: Bearer <token>.

PUT /api/v1/client/vps/{uuid}/ssh-keys

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/client/vps/{uuid}/status

Get real-time VM status from Proxmox (enriched).

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/vps/{uuid}/tasks

Authentication: an access token, sent as Authorization: Bearer <token>.