API

Catalog and orders

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

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

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

Ordering a server takes two requests: read the catalog, then order with ids from it.

Catalog

GET /services/virtual-servers/catalog

Ability: 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.

JSON
{
  "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[].plans are the plans sold in that location. A plan sold in several locations is listed in each of them under the same id, with that location's own available, systems and prices: a plan id is unique within a location, not across the catalog.
  • available: false means the plan is sold out in that location for now. An order there answers 409 out_of_stock; stock usually comes back.
  • os_template_ids are the systems the plan can be installed with in that location; the details of each are in os_templates. version is a label for people and may be null: rely on id and code.
  • prices are the billing periods the plan is sold on there, described in billing_periods. addons of a price are what can be ordered together with the server on that period, keyed by the add-on type (described in addons), each up to max_quantity. An empty addons is {}.
  • billing_periods[] carries your account's server slots, the same as billing_limits in GET /account: how many servers on that period you may have (limit), have (used) and can still order (available). null means 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-servers

Ability: vps:billing. At most 10 orders a minute per account.

Shell
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:

JSON
{
  "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.charged is the total.
  • The server is created in the status ordered, is pending while it is being built, and becomes active when it is ready, usually within a few minutes. Follow it with GET /services/virtual-servers/{id}.
  • If creation fails, the status becomes failed and the server cannot be used. Contact support with its id.

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.

Вопросы по API?

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

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