Ordering a server takes two requests: read the catalog, then order with ids from it.
Catalog
GET /services/virtual-servers/catalogAbility: vps:read.
What can be ordered, in the order you pick it in the panel: a location, a plan sold there, then a system and a billing period of that plan.
{
"data": {
"locations": [
{
"id": 2,
"code": "EYG-DC1",
"name": "Netherlands DC1",
"country_code": "NL",
"plans": [
{
"id": 1,
"name": "Core-1 Lite",
"resources": {"cpu_cores": 1, "ram_mb": 1024, "storage_gb": 30},
"available": true,
"os_template_ids": [1, 2, 4],
"prices": [
{
"billing_period_id": 5,
"price": "4.99000000",
"setup_fee": "0.00000000",
"currency": "EUR",
"addons": {
"backup_daily": {"price": "1.00000000", "max_quantity": 1},
"additional_ipv4": {"price": "2.00000000", "max_quantity": 3}
}
}
]
}
]
}
],
"billing_periods": [
{"id": 5, "code": "monthly", "name": "1 month", "hours": 720, "limit": 10, "used": 3, "available": 7}
],
"addons": [
{"type": "backup_daily", "name": "Daily Backup"},
{"type": "additional_ipv4", "name": "Additional IPv4"}
],
"os_templates": [
{"id": 1, "code": "ubuntu-server-24-04", "name": "Ubuntu Server 24.04 LTS", "family": "linux", "version": "24.04"}
]
}
}locations[].plansare the plans sold in that location. A plan sold in several locations is listed in each of them under the sameid, with that location's ownavailable, systems and prices: a planidis unique within a location, not across the catalog.available: falsemeans the plan is sold out in that location for now. An order there answers409 out_of_stock; stock usually comes back.os_template_idsare the systems the plan can be installed with in that location; the details of each are inos_templates.versionis a label for people and may benull: rely onidandcode.pricesare the billing periods the plan is sold on there, described inbilling_periods.addonsof a price are what can be ordered together with the server on that period, keyed by the add-on type (described inaddons), each up tomax_quantity. An emptyaddonsis{}.billing_periods[]carries your account's server slots, the same asbilling_limitsinGET /account: how many servers on that period you may have (limit), have (used) and can still order (available).nullmeans no limit.- Plans, prices and systems change rarely: it is fine to cache them for some minutes. The slots change with every order, so read them fresh before ordering.
Order a server
POST /services/virtual-serversAbility: vps:billing. At most 10 orders a minute per account.
curl https://panel.hostoff.net/api/v1/services/virtual-servers \
-H "Authorization: Bearer hostoff_your_token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "web-1",
"location_id": 2,
"service_plan_id": 1,
"billing_period_id": 5,
"os_template_id": 1,
"ssh_keys": ["ssh-ed25519 AAAA... me@laptop"],
"auto_renewal": true,
"addons": {"backup_daily": 1}
}'| Field | |
|---|---|
name |
required: 3 to 50 characters; letters, digits, spaces, dots and hyphens, starting and ending with a letter or digit |
location_id |
required: locations[].id from the catalog |
service_plan_id |
required: plans[].id of a plan in that location |
billing_period_id |
required: prices[].billing_period_id of that plan |
os_template_id |
required: one of that plan's os_template_ids |
password |
a password for the server: at least 10 characters with a lower-case letter, an upper-case letter and a digit |
ssh_keys |
a list of SSH public keys, up to 10. Give a password, keys, or both |
auto_renewal |
optional, true by default |
addons |
optional: {"backup_daily": 1}, an add-on type from addons of the chosen price and the quantity |
The answer is 201 Created with the new server and what was charged:
{
"data": {"id": 220, "name": "web-1", "status": "ordered", "...": "..."},
"meta": {"charged": "5.99000000", "currency": "EUR"}
}- The first period is charged at once: the plan's price, the setup fee and the add-ons.
meta.chargedis the total. - The server is created in the status
ordered, ispendingwhile it is being built, and becomesactivewhen it is ready, usually within a few minutes. Follow it withGET /services/virtual-servers/{id}. - If creation fails, the status becomes
failedand the server cannot be used. Contact support with itsid.
Why an order is refused
| Answer | Why | What to do |
|---|---|---|
402 insufficient_funds |
the balance does not cover the first period | top up in the panel |
409 limit_reached |
no free server slot on this billing period | check available of the period in the catalog's billing_periods, or contact support for a higher limit |
409 out_of_stock |
the plan is sold out in the location | try another location or later |
422 invalid_input |
an id is not in the catalog (the plan is not sold in the location, was withdrawn, the system is not available for it there), an add-on not offered with the price or above max_quantity, a weak password, an invalid key |
fix the request: fields names a malformed field, message explains a refusal of a valid-looking value |
Check before ordering: the balance in GET /account and available of the billing period in the catalog tell you in advance whether the order can go through.
Retries
An order is not protected against being sent twice yet: if a request times out and you send it again, you may get two servers, both charged. After a timeout or a network error, first read GET /services/virtual-servers and look for the server you ordered (by its name, for example) before ordering again. Protection against repeated orders is planned.