API

Virtual servers

Обновлено 16 ноября 2026 г.

Эта страница ещё не переведена на ваш язык, поэтому показана английская версия.

На этой странице

All paths on this page start with /services/virtual-servers. A server is named by its id. A server that is not yours, or that is deleted, is 404 not_found.

The server object

Every endpoint that shows or changes a server answers with this object.

JSON
{
  "id": 219,
  "name": "web-1",
  "status": "active",
  "plan": {"id": 3, "name": "Core-4"},
  "location": {"id": 4, "code": "EYG-DC1", "name": "Netherlands DC1", "country_code": "NL"},
  "os": {"code": "ubuntu-server-24-04", "name": "Ubuntu Server 24.04 LTS", "family": "linux"},
  "resources": {"cpu_cores": 4, "ram_mb": 8192, "storage_gb": 120},
  "ipv4": [
    {"address": "203.0.113.10", "gateway": "203.0.113.1", "primary": true, "addon_id": null},
    {"address": "203.0.113.25", "gateway": "203.0.113.1", "primary": false, "addon_id": 341}
  ],
  "ipv6": [
    {"prefix": "2001:db8:10:2a::/64", "gateway": "2001:db8:10::1", "enabled": true}
  ],
  "billing": {
    "period": "monthly",
    "price": "21.97000000",
    "currency": "EUR",
    "auto_renewal": true,
    "next_billing_at": "2026-12-12T16:52:06Z",
    "expires_at": "2026-12-12T16:52:06Z"
  },
  "addons": [
    {"id": 341, "name": "Additional IPv4", "type": "additional_ipv4", "status": "active", "price": "2.00000000", "billing_period": "monthly", "next_billing_at": "2026-12-12T16:52:06Z"}
  ],
  "notes": "Production web server",
  "created_at": "2026-11-12T16:52:06Z"
}
Field Meaning
name a label of your choice, not the server's hostname
ipv4[].primary the main address, configured in the server automatically
ipv4[].addon_id the paid add-on that holds an additional address; null for the main address and for addresses from your own BYOIP pool
ipv6[].enabled false when IPv6 is switched off: the prefix stays reserved for the server
billing.price what one billing period of the server costs, without add-ons
billing.next_billing_at when the next period is due: the server is renewed then, or it expires
billing.expires_at when a server that was not renewed is deleted for good, see When a server is not renewed
addons paid extras renewed together with the server; type is additional_ipv4 or backup_daily
notes your own notes, up to 1000 characters

Statuses

Status Meaning
ordered just ordered, waiting to be built
pending being built; it becomes active when it is ready
active running and paid for
reinstalling the OS is being reinstalled; it becomes active again
expired not renewed in time: the server is stopped. Renew it before billing.expires_at, otherwise it is deleted for good
suspended suspended by us, for example over an abuse report; contact support
failed creating or reinstalling the server failed, and it cannot be used. Contact support with its id
terminated deleted. Shown only once, in the answer to POST /{id}/terminate; after that, and after an automatic deletion, the id answers 404 not_found

Most actions need the server to be active; otherwise the answer is 409 invalid_state.

Reading

Ability: vps:read.

Request What it returns
GET / all your servers except deleted ones, as a list
GET /{id} one server
GET /{id}/status the live state of the virtual machine
GET /{id}/stats load graphs
GET /{id}/traffic collected traffic
GET /{id}/activity the server's activity log
GET /{id}/guest-agent whether changes can be applied without a reboot
GET /{id}/rdns reverse DNS names of the IPv4 addresses
GET /{id}/billing-periods periods the server can be paid for, with prices
GET /{id}/os-templates systems the server can be reinstalled with
GET /{id}/backups backups and the backup operation in progress
GET /{id}/ssh-keys the SSH keys the panel manages on the server

Live status

GET /{id}/status
JSON
{"data": {"status": "running", "lock": null, "uptime": 86400, "cpu": 0.0315, "memory": {"used": 1073741824, "max": 8589934592}}}

status is running or stopped, or unknown when the state could not be read right now: ask again a little later. lock names an operation that holds the machine right now (for example backup), during which most actions are refused. uptime is in seconds, cpu is the load as a fraction of the server's cores (1 = all cores busy), memory is in bytes.

Graphs

GET /{id}/stats?timeframe=hour

timeframe is hour (default), day, week, month or year. The answer is {"data": {"timeframe": "hour", "points": [...]}}; each point has time (Unix timestamp), cpu (fraction), mem and maxmem (bytes), netin and netout, diskread and diskwrite (bytes per second).

Traffic

GET /{id}/traffic?from=1762905600&to=1765497600&granularity=day
Parameter
from, to required, Unix timestamps; to is cut at the current hour
granularity day (default), hour (a range of 31 days at most) or summary
JSON
{"data": {"granularity": "day", "from": 1762905600, "to": 1765497600, "total": null, "points": [{"bucket": 1762905600, "bytes_in": 52428800, "bytes_out": 157286400, "bytes_total": 209715200}]}}

With summary, points is empty and total holds one object with bytes_in, bytes_out and bytes_total.

Activity

GET /{id}/activity?page=1

Newest first, 10 entries a page. Each entry has id, action, description, category, status, error_message, ip_address, user_name and created_at. meta has current_page, last_page, per_page and total.

Power

POST /{id}/power

Ability: vps:power.

JSON
{"action": "reboot"}
Action What it does
start power on
shutdown ask the system to shut down cleanly
stop power off at once, like pulling the plug
reboot ask the system to restart cleanly
reset hard restart at once

The answer {"data": {"action": "reboot"}} means the command was accepted. Follow the result with GET /{id}/status.

Settings

Ability: vps:manage. Each answers with the server object (rDNS: with the rDNS list).

Request Body
PATCH /{id}/name {"name": "web-1"}: 3 to 50 characters; letters, digits, spaces, dots and hyphens, starting and ending with a letter or digit
PATCH /{id}/notes {"notes": "..."}: up to 1000 characters, null clears them
PATCH /{id}/rdns {"ip": "203.0.113.10", "ptr": "mail.example.com"}: ip is one of the server's IPv4 addresses, ptr: null removes the record

The rDNS list, of GET /{id}/rdns and of the change, has one entry per IPv4 address: {"data": [{"ip": "203.0.113.10", "ptr": "mail.example.com"}]}, with ptr: null where no name is set.

Password and SSH keys

Ability: vps:manage.

Each change can be applied two ways:

  • The plain path stores the change at once; the server picks it up at the next reboot. The answer has "requires_reboot": true.
  • The .../agent path applies it inside the running server at once, through the QEMU guest agent. The answer has "requires_reboot": false. Check GET /{id}/guest-agent first: {"data": {"available": true}}.
Request Body
POST /{id}/password {"password": "..."}
POST /{id}/password/agent {"password": "..."}
POST /{id}/ssh-keys {"ssh_keys": ["ssh-ed25519 AAAA... me@laptop"]}
POST /{id}/ssh-keys/agent {"ssh_keys": [...]}
  • A password has at least 10 characters with a lower-case letter, an upper-case letter and a digit. A password is never sent back by the API.
  • SSH keys are always sent as the whole set: adding and removing a key are the same operation. Read the current set with GET /{id}/ssh-keys, change it, send it back. The answer includes the new set.
  • Up to 10 keys, one key per list item. Accepted types: ssh-ed25519, ecdsa-sha2-nistp256/384/521 and ssh-rsa of 2048 bits or more.
  • An empty list removes all keys, and is accepted only while the server has a password: otherwise you would lock yourself out.
  • The agent path leaves alone keys you added inside the server by hand.
  • SSH keys are not supported on Windows servers. Keys can be saved 10 times an hour per server, both ways together.
JSON
{"data": {"requires_reboot": true, "ssh_keys": [{"type": "ssh-ed25519", "comment": "me@laptop", "fingerprint": "SHA256:mVPwvezndPv/ARoIadVY98vAC0g+P/5633yTC4d/wXE", "key": "ssh-ed25519 AAAA... me@laptop"}]}}

Network

An address is always named by the IP itself, as in ipv4[].address of the server object. Each change answers with the server object and a meta block about what happened. Network changes of one server run one at a time: a second one started during the first gets 409 busy.

Request Ability Body What happens
POST /{id}/change-ip vps:billing {"ip": "203.0.113.10"} the address is replaced with a new one. A fixed fee is charged; free when the new address comes from your own BYOIP pool
POST /{id}/primary-ip vps:manage {"ip": "203.0.113.25"} another address of the server becomes the main one. Free
PATCH /{id}/ipv6 vps:manage {"enabled": false} IPv6 is switched off or back on; the prefix stays with the server. Free, reboots the server
POST /{id}/additional-ipv4 vps:billing none one more IPv4 is added
POST /{id}/additional-ipv4/{addon_id}/cancel vps:billing none a paid additional address is given up

meta of an IP replacement:

JSON
{"meta": {"old_ip": "203.0.113.10", "new_ip": "203.0.113.77", "charged": "1.00000000", "currency": "EUR", "rebooted": true}}
  • Replacing the main address, changing the main address and switching IPv6 reboot the server to apply the change; meta.rebooted tells whether this change did. Replacing or adding an additional address does not: such an address is not configured in the server automatically, set it up in the system yourself.
  • An additional IPv4 is an add-on: the rest of the current billing period is charged at once, then the address renews with the server. meta has the new ip, its addon_id (null when it came free from your BYOIP pool), charged and currency.
  • Cancelling an additional address takes addon_id from the server object. It happens at once and is not refunded.

Console

POST /{id}/console

Ability: vps:manage.

What a noVNC client needs to show the server's screen:

JSON
{"data": {"websocket_url": "wss://panel.hostoff.net/api/vortex/wss/...", "password": "..."}}
  • The connection is made for this call and must be opened within about 10 seconds. Request it at the moment a user opens the console, and request it again to reconnect.
  • In a browser with noVNC 1.4 or later: new RFB(element, data.websocket_url, { credentials: { password: data.password } }). The WebSocket goes through our domain, so the page itself can be on yours.
  • The screen of a server is full access to it. Do not store the answer and do not pass it to anyone but the user who opened the console.
  • At most 30 consoles an hour per server and 5 open at the same time.

Backups

The platform makes scheduled backups by itself, and the list is always visible. Creating, restoring and deleting backups needs the backup add-on on the server; without it these requests answer 409 not_supported.

GET /{id}/backups
JSON
{
  "data": {
    "can_manage": true,
    "addon": {"status": "active", "price": "4.39000000", "currency": "EUR", "paid_until": "2026-12-12T16:52:06Z"},
    "addon_offer": null,
    "active_task": null,
    "last_task": {"id": 77, "action": "create", "backup_id": null, "status": "completed", "failure_reason": null, "created_at": "2026-11-14T10:00:00Z", "finished_at": "2026-11-14T10:03:12Z"},
    "backups": [
      {"id": "2026-11-14T10:00:05Z", "type": "manual", "size": 2147483648, "verification": "ok", "protected": false, "created_at": "2026-11-14T10:00:05Z"}
    ]
  }
}
Field Meaning
can_manage whether backups can be created, restored and deleted now
addon the server's backup add-on, when it has one
addon_offer what buying the add-on costs: price per billing_period and first_charge, the part charged now for the rest of the current period, in currency. null when it is not offered or already bought
active_task, last_task the operation in progress, and the last one that finished
backups[].id the name of the backup in the requests below
backups[].type auto for scheduled backups, manual for the ones you made
backups[].verification the result of the integrity check (ok, failed), null while not checked
backups[].protected a protected backup cannot be deleted: the answer is 409 invalid_state
Request Ability What it does
POST /{id}/backups vps:manage create a backup now
POST /{id}/backups/{backup_id}/delete vps:manage delete a backup
POST /{id}/backups/{backup_id}/restore vps:destroy restore the server from a backup
POST /{id}/backups/addon vps:billing buy the backup add-on; meta has addon_id, charged, currency
POST /{id}/backups/addon/cancel vps:billing cancel the add-on at once, without a refund; existing backups stay listed
  • An operation is queued and the answer is its task. While it runs, GET /{id}/backups shows it as active_task; then as last_task. A task's status is queued, running, completed or failed.
  • Only one backup operation runs at a time per server: a second one gets 409 busy.
  • Restoring hard-stops the server and overwrites its disks: everything that changed after the backup is lost. That is why it needs vps:destroy.
  • Per server and hour: 2 backups by hand, 3 restores, 10 deletions.

Renewal and billing period

Ability: vps:billing. Money is charged from the account balance; amounts are never sent in requests.

Request Body What it does
POST /{id}/renew none pays for one more period
PATCH /{id}/auto-renewal {"auto_renewal": true} switches automatic renewal on or off
POST /{id}/change-billing-period {"billing_period_id": 5} moves the server to another billing period
  • Renewal pays for the server and its add-ons together, and meta.charged is the total. You can renew ahead of time and more than once: each call adds a period. Renewing an expired server makes it active again and starts it.
  • Changing the period charges nothing now: the new period and its price apply from the next renewal. Take the id from GET /{id}/billing-periods, which lists each period's price, addons_price, total_price, is_current and is_available. It is not possible for a server with an individual price or configuration (can_change_period: false), nor to a period on which one of its add-ons is not sold: both answer 409 not_supported. A period with no free server slot answers 409 limit_reached (see billing_limits in GET /account); a period the server is already on, or one not sold for its plan and location, answers 422 invalid_input.

When a server is not renewed

At billing.next_billing_at a server with auto-renewal on is renewed from the balance, together with its add-ons. If auto-renewal is off, or the balance does not cover the server and its add-ons:

  1. The server becomes expired and is stopped. Its disks and addresses are kept for now.
  2. Until billing.expires_at, POST /{id}/renew brings it back: it becomes active and is started. Reading and deleting still work; every other action answers 409 invalid_state. The grace period depends on the billing period: currently 24 hours for hourly servers, 48 hours for daily and 3 days for longer periods.
  3. At billing.expires_at the server is deleted for good, the same as POST /{id}/terminate: its data and add-ons are gone, its addresses are released, nothing is refunded. It cannot be restored.

To keep a server, keep auto-renewal on and enough money on the balance, or renew it ahead of time.

Reinstall

POST /{id}/reinstall

Ability: vps:destroy.

JSON
{"os_template_id": 1, "password": "Str0ngPassw0rd", "ssh_keys": ["ssh-ed25519 AAAA... me@laptop"]}
  • Everything on the server's disk is erased. The addresses and resources stay.
  • Take os_template_id from GET /{id}/os-templates: only the systems available for this server are listed.
  • Give a password, SSH keys, or both. The same rules apply as in Password and SSH keys.
  • The answer is the server in the status reinstalling; it becomes active again when the system is ready. At most 3 reinstalls an hour per server.

Delete

POST /{id}/terminate

Ability: vps:destroy.

  • The server, its data and its add-ons are deleted for good and its addresses are released. Deletion cannot be undone.
  • Nothing is refunded, not even the unused part of the paid period.
  • Possible for servers in the status active, expired or suspended. A server that is ordered, pending, reinstalling or failed answers 409 invalid_state.
  • The answer is the server in the status terminated, the last time it is shown: from then on it is not in the list, and its id answers 404 not_found.

Neither reinstalling nor deleting asks for a confirmation in the request: the call with a token that has vps:destroy is the confirmation. Give that ability only to the tokens that need it.

Вопросы по API?

Поддержка поможет с интеграцией и доступом.

Написать в поддержку