Customer API

The customer API is a Bearer-token HTTP API for scripts. It does not use the dashboard cookie. Create a key on API. The full token is shown once; we store only a sha256 hash.

Authentication

Every request sends the key as Authorization: Bearer. Keys start with smx_live_ followed by 32 hex characters. A missing, malformed, revoked, expired, or unknown key returns 401.

A key can be given an expiry date when it is created; after that day it stops working. Keys without an expiry never stop working on their own — rotate them if one may have leaked. Rotating from the API page issues a replacement with the same name and scopes and revokes the old key immediately. The full token is shown once.

curl https://scalemaxcloud.com/api/v1/account \
  -H "Authorization: Bearer smx_live_…"

Scopes

read lists servers, backups, usage and account. Write is required for power actions, backups, snapshots, console sessions, rescue and firewall changes. A write key may also read. Wrong scope is 403.

Rate limit

60 requests per minute per key. The counter is an in-memory map on the process that handled the request, so it is approximate if more than one Node process is serving. Over the limit: 429 with a Retry-After header (seconds).

Response shape

Success is { "data": … }. Failure is { "error": { "code", "message" } }. 401 bad key, 403 wrong scope or not your server, 429 rate limit.

List servers

Each row is id, label, status, cpu, ram, disk, ipv4 (private), ssh_host, ssh_port, ssh_command (the public route, or null while the server is not reachable), terminal_url, expires_at.

curl https://scalemaxcloud.com/api/v1/instances \
  -H "Authorization: Bearer smx_live_…"

One server

curl https://scalemaxcloud.com/api/v1/instances/1 \
  -H "Authorization: Bearer smx_live_…"

Power

POST action: start, stop, or restart. Scope write. Suspended guests refuse with 403.

curl -X POST https://scalemaxcloud.com/api/v1/instances/1/power \
  -H "Authorization: Bearer smx_live_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

Usage

GET /api/v1/instances/1/stats (read) returns the live gauges plus the sampled series. ?timeframe=hour|day|week picks the window and defaults to hour; anything else is 400. Rates are bytes per second. netInBytes and netOutBytes are the byte totals for the window, estimated by integrating the sampled rates, so treat them as an estimate rather than an accounting counter. memUsedMb is memory in use by programs, read inside the server, when memSource is guest; when the server does not report it, memSource is hypervisor and the figure also counts the file cache Linux keeps in free memory. memSeriesSource says the same for the series.

curl "https://scalemaxcloud.com/api/v1/instances/1/stats?timeframe=day" \
  -H "Authorization: Bearer smx_live_…"

Console

POST (write) opens a one-time serial-console session and returns wsUrl and expiresAt. The URL is single-use, opens a root shell, and must be kept out of logs. At most ten console sessions per server per hour, same budget as the dashboard button; over that is 429.

curl -X POST https://scalemaxcloud.com/api/v1/instances/1/console \
  -H "Authorization: Bearer smx_live_…"

Backups

GET lists the server's backups. POST starts one (write). Same instance id as the dashboard.

curl https://scalemaxcloud.com/api/v1/instances/1/backups \
  -H "Authorization: Bearer smx_live_…"

curl -X POST https://scalemaxcloud.com/api/v1/instances/1/backups \
  -H "Authorization: Bearer smx_live_…"

Restore a backup

POST (write) restores a completed backup. The body must carry {"confirm":true}. Without targetInstanceId the backup's own server is overwritten. With it, the backup is restored into another server you own — never across accounts — and that server's disk is replaced with the backup, so its current contents are lost. The restore runs on the hypervisor after this call returns (restoring: true); poll GET /api/v1/instances/<id> until the status settles.

curl -X POST https://scalemaxcloud.com/api/v1/backups/12/restore \
  -H "Authorization: Bearer smx_live_…" \
  -H "Content-Type: application/json" \
  -d '{"confirm":true,"targetInstanceId":3}'

Snapshots

GET lists restore points and the cap (read). POST creates one and takes an optional name (write). DELETE removes one by name (write). Creating beyond the cap is refused until one is deleted.

curl -X POST https://scalemaxcloud.com/api/v1/instances/1/snapshots \
  -H "Authorization: Bearer smx_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"before-upgrade"}'

curl -X DELETE https://scalemaxcloud.com/api/v1/instances/1/snapshots/before-upgrade \
  -H "Authorization: Bearer smx_live_…"

Rescue

A locked-out guest is recovered through the guest agent. POST /rescue/password (write) sets a new root password and returns it once in the response — store it, it is not shown again. GET/POST/DELETE /rescue/ssh-keys list fingerprints (read), append a key (write), and remove one by ?fingerprint=SHA256:… (write). Removing the last key is refused while password login is disabled in the guest. The server must be running.

curl -X POST https://scalemaxcloud.com/api/v1/instances/1/rescue/password \
  -H "Authorization: Bearer smx_live_…"

curl https://scalemaxcloud.com/api/v1/instances/1/rescue/ssh-keys \
  -H "Authorization: Bearer smx_live_…"

Firewall

GET /api/v1/instances/1/firewall (read) returns the inbound rules, the default and whether they are applied; PUT (write) replaces and applies them. Body and examples: Firewall.

Account

Email, credit balance in paise, and how many instances you have.

curl https://scalemaxcloud.com/api/v1/account \
  -H "Authorization: Bearer smx_live_…"