API documentation

HelloServ API (v1)

The API lets your own tools do what you do in your client area: list your services with their specifications, read their live status and IP addresses, start, restart or stop a server, reinstall a VPS or a dedicated server, get your invoices, and order game servers and VPS paid with your account balance. It is a JSON REST API over HTTPS.

https://panel.helloserv.fr/api/v1

Authentication and scopes

Create a key in your client area, under My Profile > Security > API keys. Creating a key requires two-factor authentication (authenticator app or passkey) on your account. The key is shown once: store it like a password. You can revoke it at any time from the same page, which also lists the latest calls made with your keys.

Send the key in the Authorization header of every request:

curl https://panel.helloserv.fr/api/v1/account \
  -H "Authorization: Bearer hsk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Each key has scopes, chosen when you create it:

ScopeGives access to
readAccount, services, specifications, status, IP addresses, available systems, invoices. Always included.
powerPower actions: start, stop, restart (and forced power off or reset on dedicated servers).
reinstallReinstallation of a VPS or a dedicated server. All data on the server is erased.
orderOrders of game servers and VPS, paid with your account balance. Never given by default.

A request body, when there is one, is a JSON object sent with Content-Type: application/json. Dates are ISO 8601 with the Paris time offset. Amounts are in euros: subtotal excludes VAT, total includes it, tax_rate is a fraction (0.2 = 20 %).

Limits

Errors

An error comes with an HTTP status and a stable code:

{"error": {"code": "service_not_found", "message": "Service not found."}}
StatusCodes
400idempotency_key_required, unknown_field, invalid_json, invalid_parameter, invalid_action, weak_password, unknown_system, invalid_hostname, invalid_ssh_key, invalid_disk_layout, invalid_request
401missing_key, invalid_key (unknown or revoked)
402insufficient_balance, payment_failed
403insufficient_scope, ip_not_allowed
404not_found, service_not_found, invoice_not_found, product_not_found
405method_not_allowed
409out_of_stock, order_in_progress, service_not_active, not_supported, action_in_progress, reinstall_in_progress, not_supported_by_hardware, management_unavailable, reinstall_finished, too_late, disk_inventory_missing, needs_staff
413body_too_large
422invalid_product, invalid_offer, invalid_period, invalid_os, invalid_addon, country_required, idempotency_key_reused
429rate_limited, too_many_actions, too_soon, too_many_failures, order_limit_reached
502, 503hypervisor_unavailable, hypervisor_error, management_error, gamepanel_unavailable, gamepanel_error, reinstall_unavailable, api_disabled: retry later

IP allowlist

Each key can be restricted to addresses or ranges (IPv4, IPv6, CIDR notation such as 203.0.113.0/24 or 2001:db8::/48), 20 at most. Set the list when you create the key, or later on the same page (your two-factor authentication is asked again). A key without a list works from any address. A call from another address is refused with 403 ip_not_allowed and appears in your call log. A server with IPv6 usually calls over IPv6: list both of its addresses.

Account

GET/account

Your account and the key used for the call.

{"data": {
  "account": {"id": 1234, "name": "Jane Doe", "created_at": "2026-03-02T10:15:00+01:00", "balance": 50.00, "currency": "EUR"},
  "key": {"name": "monitoring", "prefix": "hsk_1a2b3c4d", "scopes": ["read", "power"], "ip_allowlist": ["203.0.113.0/24"], "created_at": "2026-11-21T18:00:00+01:00"}
}}

Services

GET/services

All your services. Optional filters: status (active, suspended, pending, provisioning, cancelled, expired) and type (dedicated, vps, game, protection).

curl "https://panel.helloserv.fr/api/v1/services?status=active&type=dedicated" \
  -H "Authorization: Bearer $HELLOSERV_KEY"
{"data": [
  {"id": 3543, "name": "DED-Xeon-1", "type": "dedicated", "product": "dedicatedservers", "status": "active",
   "created_at": "2026-11-16T13:00:20+01:00", "expires_at": "2026-12-16T13:00:20+01:00",
   "primary_ip": "203.0.113.10", "actions": {"power": true, "reinstall": true}}
]}

GET/services/{id}

One service with its specifications, billing information and network. For a dedicated server, network lists the main and additional IPv4 addresses, and the prefix, gateway and DNS servers when remote management knows them. For a game server, it lists the ports.

{"data": {
  "id": 3543, "name": "DED-Xeon-1", "type": "dedicated", "product": "dedicatedservers", "status": "active",
  "created_at": "2026-11-16T13:00:20+01:00", "expires_at": "2026-12-16T13:00:20+01:00",
  "primary_ip": "203.0.113.10", "actions": {"power": true, "reinstall": true},
  "billing": {"period": "monthly", "auto_renewal": true, "cancellation_requested": false},
  "specs": {"offer": "Xeon E5", "cpu": "1x Intel Xeon E5-2640v2 @ 3.0GHz", "cpu_details": "Total: 6 Cores / 12 Threads",
            "ram_gb": 32, "ram_type": "DDR3", "disks": [{"type": "SSD", "size_gb": 250, "quantity": 1}], "os": "Ubuntu 24.04"},
  "network": {"primary_ip": "203.0.113.10", "ips": ["203.0.113.10", "203.0.113.11", "203.0.113.12"],
              "prefix": 24, "gateway": "203.0.113.1", "dns": ["1.1.1.1", "9.9.9.9"]}
}}

VPS: specs gives cpu_cores, ram_gb, storage_gb, os, hostname. Game server: network gives primary_ip, primary_port and ports.

Status

GET/services/{id}/status

Live state, read from the server management card (dedicated), the hypervisor (VPS) or the game panel. Active services only.

{"data": {
  "power": "on", "read_from_hardware": true, "model": "PowerEdge R630",
  "available_actions": ["start", "stop", "restart", "poweroff", "reset"],
  "current_action": null,
  "recent_actions": [{"id": 812, "action": "restart", "status": "done", "by": "customer", "at": "2026-11-21T18:02:11+01:00"}]
}}

Dedicated: power is on, off or unknown; an action status is in_progress, done, failed, timeout or superseded. VPS: power is running, stopped, suspended, rescue or unknown, with cpu_percent, memory, disk, installing and the current power_operation. Game server: power is running, offline, starting, stopping, installing or install_failed, with CPU, memory and players.

Power actions

POST/services/{id}/power scope power

Serviceaction
Dedicated serverstart, stop (clean shutdown), restart, poweroff (forced), reset (forced restart)
VPSstart, stop, restart: stop and restart first ask the system to shut down cleanly, then force it after a delay
Game serverstart, stop, restart
curl -X POST https://panel.helloserv.fr/api/v1/services/3543/power \
  -H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
  -d '{"action": "restart"}'
{"data": {"action": "restart", "accepted": true, "operation_id": 813}}

The answer is 202: the action is accepted and runs in the background. Follow it with GET /services/{id}/status.

Reinstallation

GET/services/{id}/reinstall

What can be installed. VPS: systems with their id. Dedicated server: systems with their code, the disks, whether you choose the disk (disk_choice), raid1_possible, the languages, and the current reinstallation if there is one.

{"data": {"available": true,
  "systems": [{"code": "ubuntu-24.04", "name": "Ubuntu 24.04", "family": "linux"}, {"code": "debian-13", "name": "Debian 13", "family": "linux"}],
  "disks": [{"ref": "sda", "number": 1, "size_bytes": 480103981056, "type": "ssd"}],
  "disk_choice": true, "raid1_possible": false, "languages": ["fr", "en"], "password_min_length": 12,
  "current": null}}

POST/services/{id}/reinstall scope reinstall

Everything on the server is erased. Without a password, a random one is generated and returned once, in this response only.

VPS fields: os_id (required), password (12 characters or more).

curl -X POST https://panel.helloserv.fr/api/v1/services/2210/reinstall \
  -H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
  -d '{"os_id": 1194}'

Dedicated server fields:

Field
osRequired: a system code from GET …/reinstall.
hostnameRequired. 15 characters at most for Windows.
language, timezoneRequired: one of languages, and a time zone such as Europe/Paris.
passwordOptional, 12 to 128 characters, three kinds of characters out of four.
ssh_keyOptional public key (Linux).
diskDisk ref, required when disk_choice is true.
raid1, data_disks, partitioningOptional (Linux): true, a list of disk refs, simple or lvm.
curl -X POST https://panel.helloserv.fr/api/v1/services/3543/reinstall \
  -H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
  -d '{"os": "ubuntu-24.04", "hostname": "node-1", "language": "en", "timezone": "Europe/Paris", "disk": "sda", "ssh_key": "ssh-ed25519 AAAA… me@host"}'
{"data": {"accepted": true, "password": "generated-once",
  "reinstall": {"status": "in_progress", "step": 1, "progress": 5, "phase": null, "cancellable": true,
                "system": "Ubuntu 24.04", "hostname": "node-1", "requested_by": "customer",
                "created_at": "2026-11-21T18:10:00+01:00", "finished_at": null}}}

Follow it with GET /services/{id}/reinstall (current): status goes to installing then ready, or failed, cancelled, expired.

POST/services/{id}/reinstall/cancel scope reinstall

Dedicated servers, as long as cancellable is true (the disks have not been written yet).

Invoices

GET/invoices

Newest first. Pagination: page (from 1) and per_page (20 by default, 100 at most).

{"data": [
  {"number": "INV-2026-000812", "type": "renewal", "status": "paid", "issued_at": "2026-11-09T13:00:00+01:00",
   "due_date": "2026-11-16T13:00:00+01:00", "paid_at": "2026-11-09T13:02:41+01:00", "currency": "EUR",
   "subtotal": 100, "discount": 0, "tax_rate": 0.2, "tax": 20, "total": 120, "pdf": "/api/v1/invoices/INV-2026-000812/pdf"}
], "meta": {"page": 1, "per_page": 20, "total": 7}}

status: pending, processing, overdue, paid, cancelled, expired. An unpaid notice has a number starting with AE-; it gets its INV- number once paid.

GET/invoices/{number}

The same fields plus items (name, description, quantity, unit_price, total, excluding VAT).

GET/invoices/{number}/pdf

curl -o invoice.pdf https://panel.helloserv.fr/api/v1/invoices/INV-2026-000812/pdf \
  -H "Authorization: Bearer $HELLOSERV_KEY"

Catalog

GET/catalog

Products you can order through the API (game servers and VPS), with the number of offers sold today.

{"data": [{"type": "minecraft", "category": "game", "name": "Minecraft", "offers": 6},
          {"type": "vpsintel", "category": "vps", "name": "VPS Intel", "offers": 5}]}

GET/catalog/{type}

The offers of a product with their specifications and their prices for your account: excl_tax, and total, what you pay, VAT included according to your country and status. Also the billing periods with their discount, the systems of a VPS (os) and the monthly add-ons. Values below are an example.

{"data": {"type": "vpsintel", "category": "vps", "name": "VPS Intel", "currency": "EUR", "tax": {"base": "incl_tax", "rate": 0.2},
  "periods": [{"id": "monthly", "months": 1, "discount_percent": 0}, {"id": "annually", "months": 12, "discount_percent": 10}],
  "os": [{"id": "debian12", "label": "Debian 12"}], "os_default": "debian12",
  "addons": [{"id": 12, "name": "Backups", "price_monthly_excl_tax": null, "price_percent_of_offer": 20, "max_quantity": 1}],
  "offers": [{"id": 3, "name": "VPS-2", "cpu_cores": 2, "ram_gb": 4, "storage_gb": 60, "in_stock": true,
    "prices": {"monthly": {"excl_tax": 8.00, "total": 9.60}, "annually": {"excl_tax": 86.40, "total": 103.68}}}]}}

Orders

Order a game server or a VPS paid with your account balance (add funds from your client area). Prices, VAT, invoice and automatic delivery are the same as for an order placed in the client area. Needs the order scope.

POST/orders scope order

FieldValue
typeProduct, from GET /catalog.
offer_idOffer, from GET /catalog/{type}.
periodmonthly (default), quarterly or annually.
osSystem of a VPS, from the catalog. Default system if omitted.
addonsOptional: add-on ids, or objects {"id": 12, "quantity": 2}.
dry_runJSON boolean. true: returns the exact price for your account and your balance, without ordering.

Any other field is refused (400 unknown_field), and so is a dry_run that is not a JSON boolean: a typo never turns a quote into an order. Each real order needs an Idempotency-Key header (8 to 64 characters: letters, digits, - _ . :), unique per order. Retrying with the same key (timeout, network error) never orders twice: you get the first answer again, with Idempotent-Replayed: true. If the order was refused before anything was created (balance too low, offer out of stock), the key is free again: fix the cause and retry with it.

curl -X POST https://panel.helloserv.fr/api/v1/orders \
  -H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7f3a9c21" \
  -d '{"type": "vpsintel", "offer_id": 3, "period": "monthly", "os": "debian12"}'

201: the paid invoice and the services created. A service starts as pending: follow it with GET /services/{id} until it is active.

{"data": {
  "order": {"id": 42, "status": "paid", "idempotency_key": "order-7f3a9c21"},
  "invoice": {"number": "INV-2026-001234", "status": "paid", "total": 9.60, "currency": "EUR", "pdf": "/api/v1/invoices/INV-2026-001234/pdf"},
  "services": [{"id": 5678, "name": "vps-2", "status": "pending", "url": "/api/v1/services/5678"}],
  "balance": 40.40
}}

Balance too low: 402 insufficient_balance, nothing is created. Add-ons paid once (installation services) are not available through the API. Your country must be set in your profile, it sets the VAT: otherwise 422 country_required.

GET/orders

The orders placed through the API on your account, latest first (?page, ?per_page up to 100): status, key used, product, total, invoice and services.

Questions or a missing feature: open a ticket from your client area.