Documentație API

Comandă, pornește, salvează și șterge serverele din scripturi, pipeline-uri CI și propriile tale unelte.

Primii pași

API-ul este o interfață REST simplă peste HTTPS, cu corpuri JSON și token-uri bearer. Tot ce poți face din consolă poți face și de aici.

Creează un token din Setări → API.
Acordă-i doar permisiunile de care are nevoie scriptul: orice token poate citi; power, servers, snapshots și ssh-keys se acordă separat.
Trimite-l ca Bearer token în antetul Authorization.

curl https://cloudlinux.ro/api/v1/servers \
  -H "Authorization: Bearer cl_your_token" \
  -H "Accept: application/json"

curl -X POST https://cloudlinux.ro/api/v1/servers/server-abc123/power \
  -H "Authorization: Bearer cl_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

URL de bază: https://cloudlinux.ro/api/v1
Format: JSON la intrare și la ieșire. Listele vin sub "data"; listele paginate adaugă "links" și "meta".
Permisiuni: read (mereu), power, servers, snapshots, ssh-keys. O permisiune lipsă răspunde cu 403.
Limită de cereri: 120 de cereri pe minut per token. Interoghează un server în curs de instalare la 10-15 secunde, nu mai des.

Account

GET/mescope: read

The account behind the token, its credit and the token’s own scopes.

GET/billingscope: read

Credit, hourly and monthly burn, days left, month-to-date spend and budget.

GET/billing/transactionsscope: read

Transaction history, newest first, 50 per page (?page=).

Catalog

GET/locationsscope: read

Every location you can order in, with its plans (hourly and monthly prices) and operating-system images.

Use the plan, location and image ids from here when ordering.

GET/appsscope: read

One-click applications (installed on Ubuntu; pass app_id instead of image_id).

Servers

GET/serversscope: read

Your servers. Filters: ?project_id=, ?status=.

POST/serversscope: servers

Order a server. Provisioning is asynchronous: poll the server until status is "running".

{ "plan_id": 12, "location_id": 3, "image_id": 7, "ssh_key_ids": [1], "display_name": "web-1", "project_id": null }

Optional: app_id (replaces image_id), recipe_id, root_password (8-72 chars). Needs credit for at least one hour.

GET/servers/{id}scope: read

One server. {id} is the numeric id or the server name (server-xxxxxx).

PATCH/servers/{id}scope: servers

Rename or move to a project.

{ "display_name": "web-2", "project_id": 4 }

DELETE/servers/{id}scope: servers

Delete the server. The hour in progress is billed. Returns 204.

POST/servers/{id}/powerscope: power

Power action. Returns the server with its transient status (starting / stopping).

{ "action": "reboot" }

Actions: on, shutdown (graceful), off (forced), reboot (graceful), reset (hard).

POST/servers/{id}/reinstallscope: servers

Rebuild with a fresh operating system. Everything on the disk is lost.

{ "image_id": 7 }

GET/servers/{id}/rescale-optionsscope: read

Plans the server can move to, with in_stock and disk_ok flags.

POST/servers/{id}/rescalescope: servers

Change the plan. The server must be powered off.

{ "plan_id": 15, "upgrade_disk": false }

GET/servers/{id}/metricsscope: read

CPU, network and disk series. ?range=1h|6h|24h|7d.

Snapshots

GET/servers/{id}/snapshotsscope: read

Snapshots of a server, newest first.

POST/servers/{id}/snapshotsscope: snapshots

Take a snapshot. Stored snapshots bill hourly by size.

{ "name": "before-upgrade", "include_memory": false }

Names: 2-40 characters, letters, digits, dashes or underscores, starting with a letter. "auto-" is reserved.

POST/servers/{id}/snapshots/{snapshot}/restorescope: snapshots

Rebuild the server from the snapshot.

DELETE/servers/{id}/snapshots/{snapshot}scope: snapshots

Delete a snapshot. Returns 202 with result "deleted" or "scheduled".

SSH keys

GET/ssh-keysscope: read

Your public keys.

POST/ssh-keysscope: ssh-keys

Add a public key (OpenSSH format).

{ "name": "laptop", "public_key": "ssh-ed25519 AAAA... user@host" }

DELETE/ssh-keys/{id}scope: ssh-keys

Remove a key. Servers already created keep it.

Projects

GET/projectsscope: read

Your projects (server folders) with server counts.

POST/projectsscope: servers

Create a project.

{ "name": "Client A" }

PATCH/projects/{id}scope: servers

Rename a project.

{ "name": "Client B" }

DELETE/projects/{id}scope: servers

Delete a project. Its servers keep running, unassigned.

Răspunsuri și erori

Erorile conțin un "message" lizibil și, la validare, o hartă "errors" pe câmpuri. Mesajele urmează limba setată pe cont.

200 / 201 / 204Success. 201 after creating a resource, 204 after deleting one.

202Accepted: the work was queued (snapshot deletion).

401Missing, unknown or expired token.

403The token lacks the scope, the server is suspended, or the account is blocked.

404No such resource on this account.

409The server is busy with another operation: retry in a moment.

422Validation failed. The body lists the fields under "errors".

429Rate limit: 120 requests per minute per token.

503The platform could not complete the action right now: retry in a moment.