API v1

QoCloud REST API

The API covers the same operations as the dashboard: create a server, reboot it, reinstall the OS, renew it. JSON over HTTPS, read-only or full-access keys, and events through webhooks.

Base URLhttps://qocloud.tech/api/v1

Authentication

Create a key under Settings → API keys and send it in the Authorization: Bearer … header. Store the key as you would a password.

Quick start

Your first request

Store the token in an environment variable and list your servers.

bash

$ export QOCLOUD_TOKEN="qc_live_…"$ curl https://qocloud.tech/api/v1/servers -H "Authorization: Bearer $QOCLOUD_TOKEN"

GET/catalog

Plans and prices

Locations, plans with monthly prices in rubles, available operating systems, billing periods and period discounts (in percent). No key required.

curl

$ curl -X GET https://qocloud.tech/api/v1/catalog \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "locations": [    {      "code": "nl",      "name": "Нидерланды",      "available": true    }  ],  "plans": [    {      "id": "2c-4g-60",      "line": "start",      "cpu": 2,      "ram_gb": 4,      "disk_gb": 60,      "monthly": {        "nl": 945      }    }  ],  "os": [    "ubuntu2404",    "debian12"  ],  "periods": [    "1m",    "3m",    "6m",    "1y"  ],  "discounts": {    "1m": 0,    "3m": 15,    "6m": 20,    "1y": 25  }}

GET/balance

Balance

Account balance, monthly spend on running servers and auto-renewal status. Scope: read.

curl

$ curl -X GET https://qocloud.tech/api/v1/balance \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "balance": 4820,  "currency": "RUB",  "monthly_spend": 6241,  "auto_renew": true}

GET/servers

List servers

All servers on the account. status: provisioning, active, suspended, expired, failed; power: running or stopped. Scope: read.

curl

$ curl -X GET https://qocloud.tech/api/v1/servers \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "servers": [    {      "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",      "name": "web-01",      "status": "active",      "power": "running",      "plan": "2c-4g-60",      "cpu": 2,      "ram_gb": 4,      "disk_gb": 60,      "location": "nl",      "os": "ubuntu2404",      "ip": "203.0.113.10",      "price_month": 945,      "paid_until": "2026-12-02T09:00:00.000Z",      "created_at": "2026-06-02T09:00:00.000Z",      "last_error": null    }  ]}

POST/servers

Create a server

Charges the period price to your balance (with the 3, 6 or 12 month discount) and creates the server in 1–3 minutes. Send an Idempotency-Key header: a retry with the same key within 24 hours won’t create a second server. If your balance is insufficient, the API returns 402 with a need field. Scope: manage.

Parameters
Parameter	Description
`plan`string · required	plan id from /catalog
`location`string · required	location code: nl, de, pl, ee, cz, ch, se
`os`string · required	image from /catalog
`period`string · required	1m, 3m, 6m or 1y
`name`string · required	Latin letters, digits and hyphens, 2–60 characters

curl

$ curl -X POST https://qocloud.tech/api/v1/servers \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"plan":"2c-4g-60","location":"nl","os":"ubuntu2404","period":"1m","name":"web-02"}'

Response · 200

{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-02",    "status": "provisioning",    "power": null,    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": null,    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null  }}

GET/servers/{id}

Get a server

Current server details (status is checked against the data center). Scope: read.

Parameters
Parameter	Description
`id`string · required	server id

curl

$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-01",    "status": "active",    "power": "running",    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": "203.0.113.10",    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null  }}

GET/servers/{id}/password

Root password

The current root password. Every request is recorded in the security log. Scope: manage.

curl

$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/password \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "id": "6f1c2a9e-…",  "root_password": "k3P…"}

GET/servers/{id}/events

Server log

Who managed the server and when: the control panel (user), an API key (api, with the key name in api_key), support (admin) or automation (system). Amount: negative for a charge, positive for a refund. Newest entries first. Scope: read.

Parameters
Parameter	Description
`id`string · required	server id
`limit`number	number of entries to return, 1–200 (default 100)

curl

$ curl -X GET https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/events \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "events": [    {      "id": "0b7e…",      "at": "2026-06-02T09:05:00.000Z",      "action": "change_ip",      "label": "Смена IP",      "actor": "api",      "api_key": "deploy",      "ok": true,      "detail": "Прежний 203.0.113.10",      "amount": -150    }  ]}

POST/servers/{id}/actions/{action}

Server action

start, stop, reboot, reinstall (requires os), reset-password, change-ip (paid), renew (one month from your balance), upgrade (requires plan, you pay the difference for the rest of the period). Actions run asynchronously: the API returns 202 and the status changes within seconds to minutes. Scope: manage.

Parameters
Parameter	Description
`action`string · required	start, stop, reboot, reinstall, reset-password, change-ip, renew, upgrade
`os`string	reinstall only
`plan`string	upgrade only

curl

$ curl -X POST https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70/actions/reinstall \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"os":"debian12"}'

Response · 200

{  "ok": true,  "action": "reinstall",  "message": "Переустановка началась",  "server": {    "id": "6f1c2a9e-…",    "status": "active",    "power": "running"  }}

PATCH/servers/{id}

Update a server

Name, note, tags and auto-renewal. Send only the fields you change; auto_renew: null falls back to the account setting. Scope: manage.

Parameters
Parameter	Description
`name`string	Latin letters, digits and hyphens, 2–60 characters
`note`string \| null	a note up to 1000 characters; null removes it
`tags`string[]	the full tag list (replaces the old one)
`auto_renew`boolean \| null	auto-renewal for this server

curl

$ curl -X PATCH https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"name":"web-02","tags":["prod","eu"],"auto_renew":true}'

Response · 200

{  "server": {    "id": "6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70",    "name": "web-02",    "status": "active",    "power": "running",    "plan": "2c-4g-60",    "cpu": 2,    "ram_gb": 4,    "disk_gb": 60,    "location": "nl",    "os": "ubuntu2404",    "ip": "203.0.113.10",    "price_month": 945,    "paid_until": "2026-12-02T09:00:00.000Z",    "created_at": "2026-06-02T09:00:00.000Z",    "last_error": null,    "note": null,    "tags": [      "eu",      "prod"    ],    "auto_renew": true  }}

GET/ssh-keys

List SSH keys

Public keys on the account with SHA256 fingerprints, the same as in Settings. Scope: read.

curl

$ curl -X GET https://qocloud.tech/api/v1/ssh-keys \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "ssh_keys": [    {      "id": "3a1b…",      "name": "laptop",      "type": "ssh-ed25519",      "fingerprint": "SHA256:4f2A…",      "public_key": "ssh-ed25519 AAAAC3Nza… laptop",      "created_at": "2026-06-02T09:00:00.000Z"    }  ]}

POST/ssh-keys

Add an SSH key

Accepts ed25519, ECDSA and RSA keys of 2048 bits or more. Adding the same key twice returns 409. Up to 20 keys. Responds with 201. Scope: manage.

Parameters
Parameter	Description
`public_key`string · required	the line from ~/.ssh/id_ed25519.pub
`name`string	a label; defaults to the key comment

curl

$ curl -X POST https://qocloud.tech/api/v1/ssh-keys \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "Content-Type: application/json" \  -d '{"name":"laptop","public_key":"ssh-ed25519 AAAAC3Nza… laptop"}'

Response · 200

{  "ssh_key": {    "id": "3a1b…",    "name": "laptop",    "type": "ssh-ed25519",    "fingerprint": "SHA256:4f2A…",    "public_key": "ssh-ed25519 AAAAC3Nza… laptop",    "created_at": "2026-06-02T09:00:00.000Z"  }}

DELETE/ssh-keys/{id}

Delete an SSH key

Removes the key from the account. Servers you already created keep it in authorized_keys, so remove it there yourself. Scope: manage.

curl

$ curl -X DELETE https://qocloud.tech/api/v1/ssh-keys/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN"

Response · 200

{  "id": "3a1b…",  "deleted": true}

DELETE/servers/{id}

Delete a server

Deletes the server and all its data. This can’t be undone. Requires an X-Confirm-Name header with the server name. The prepaid period is not refunded (see the refund policy). Scope: manage.

curl

$ curl -X DELETE https://qocloud.tech/api/v1/servers/6f1c2a9e-8b1d-4c1e-9f7a-2d3b4c5e6f70 \  -H "Authorization: Bearer $QOCLOUD_TOKEN" \  -H "X-Confirm-Name: web-01"

Response · 200

{  "id": "6f1c2a9e-…",  "status": "deleted"}

Webhooks

Events sent to your server

Set the URL and events under Settings → API → Webhooks. We send a JSON POST and wait up to 10 seconds for a 2xx response. On failure we retry after 1, 5 and 30 minutes, then 2, 6 and 12 hours. We don’t follow redirects.

server.readythe server is created and ready; data.server has the id, name and IP
server.expiringthe term is ending: 7 and 3 days ahead, 3 hours ahead and after it ends (stage)
server.renewedthe server was renewed; data.amount is the amount charged
balance.lowthe balance won’t cover upcoming renewals or dropped below your threshold
alert.firinga monitoring or uptime check alert fired
alert.resolvedthe alert cleared
payment.succeededa payment was credited to your balance

Verifying the signature

The X-QoCloud-Signature header is t=<timestamp>,v1=<HMAC-SHA256 of “t.body” with the endpoint secret>. Check the signature and reject requests older than 5 minutes.

import crypto from 'node:crypto';function verify(body, header, secret) {  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');  return crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));}

Errors and limits

Error codes

Error responses look like { "error": { "code", "message" } }. Codes do not change, so your scripts can branch on them.

401unauthorizedThe key is missing, revoked or expired.
403forbiddenThe key is read-only, or the account is blocked.
400bad_requestInvalid fields; details are in fields.
402insufficient_balanceInsufficient balance; the missing amount is in need.
404not_foundServer not found (or it belongs to another account).
409conflictThe action isn’t available right now, for example while the server is being created or is stopped.
429rate_limited120 requests per minute per key; heavy operations are limited to 10 per 10 minutes.