Documentation API

API HelloServ (v1)

L'API permet à vos propres outils de faire ce que vous faites dans votre espace client : lister vos services et leurs caractéristiques, lire leur état en direct et leurs adresses IP, démarrer, redémarrer ou arrêter un serveur, réinstaller un VPS ou un serveur dédié, récupérer vos factures, et commander des serveurs de jeu et des VPS payés avec le solde de votre compte. C'est une API REST en JSON, sur HTTPS.

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

Authentification et droits

Créez une clé dans votre espace client, dans Mon Profil > Sécurité > Clés d'API. La création demande la double authentification sur votre compte (application ou clé d'accès). La clé n'est affichée qu'une fois : gardez-la comme un mot de passe. Vous pouvez la révoquer à tout moment depuis la même page, qui montre aussi les derniers appels faits avec vos clés.

Envoyez la clé dans l'en-tête Authorization de chaque requête :

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

Chaque clé a des droits, choisis à sa création :

DroitDonne accès à
readCompte, services, caractéristiques, état, adresses IP, systèmes disponibles, factures. Toujours inclus.
powerAlimentation : démarrer, arrêter, redémarrer (et arrêt ou redémarrage forcé sur un serveur dédié).
reinstallRéinstallation d'un VPS ou d'un serveur dédié. Toutes les données du serveur sont effacées.
orderCommandes de serveurs de jeu et de VPS, payées avec le solde de votre compte. Jamais donné par défaut.

Le corps d'une requête, quand il y en a un, est un objet JSON envoyé avec Content-Type: application/json. Les dates sont au format ISO 8601 avec le décalage horaire de Paris. Les montants sont en euros : subtotal hors taxes, total TTC, tax_rate en fraction (0.2 = 20 %).

Limites

Erreurs

Une erreur arrive avec un statut HTTP et un code stable :

{"error": {"code": "service_not_found", "message": "Service not found."}}
StatutCodes
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 (inconnue ou révoquée)
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 : réessayez plus tard

Adresses autorisées

Chaque clé peut être limitée à des adresses ou des plages (IPv4, IPv6, notation CIDR comme 203.0.113.0/24 ou 2001:db8::/48), 20 au plus. Donnez la liste à la création de la clé, ou plus tard sur la même page (votre double authentification est redemandée). Une clé sans liste marche depuis toutes les adresses. Un appel venu d'une autre adresse est refusé avec 403 ip_not_allowed et figure dans votre journal des appels. Un serveur qui a de l'IPv6 appelle souvent en IPv6 : mettez ses deux adresses.

Compte

GET/account

Votre compte et la clé utilisée pour l'appel.

{"data": {
  "account": {"id": 1234, "name": "Jeanne Martin", "created_at": "2026-03-02T10:15:00+01:00", "balance": 50.00, "currency": "EUR"},
  "key": {"name": "supervision", "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

Tous vos services. Filtres facultatifs : status (active, suspended, pending, provisioning, cancelled, expired) et 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}

Un service avec ses caractéristiques, ses informations de facturation et son réseau. Pour un serveur dédié, network donne l'adresse IPv4 principale et les additionnelles, puis le préfixe, la passerelle et les serveurs DNS quand la gestion à distance les connaît. Pour un serveur de jeu, il donne les 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 donne cpu_cores, ram_gb, storage_gb, os, hostname. Serveur de jeu : network donne primary_ip, primary_port et ports.

État

GET/services/{id}/status

État en direct, lu sur la carte de gestion du serveur (dédié), sur l'hyperviseur (VPS) ou sur le panel de jeu. Services actifs seulement.

{"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"}]
}}

Dédié : power vaut on, off ou unknown ; le status d'une action vaut in_progress, done, failed, timeout ou superseded. VPS : power vaut running, stopped, suspended, rescue ou unknown, avec cpu_percent, memory, disk, installing et l'opération d'alimentation en cours (power_operation). Serveur de jeu : power vaut running, offline, starting, stopping, installing ou install_failed, avec le processeur, la mémoire et les joueurs.

Alimentation

POST/services/{id}/power droit power

Serviceaction
Serveur dédiéstart, stop (arrêt propre), restart, poweroff (arrêt forcé), reset (redémarrage forcé)
VPSstart, stop, restart : l'arrêt et le redémarrage demandent d'abord au système de s'arrêter proprement, puis le forcent après un délai
Serveur de jeustart, 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}}

La réponse est 202 : l'action est acceptée et s'exécute en arrière-plan. Suivez-la avec GET /services/{id}/status.

Réinstallation

GET/services/{id}/reinstall

Ce qui peut être installé. VPS : systems avec leur id. Serveur dédié : systems avec leur code, les disks, si vous choisissez le disque (disk_choice), raid1_possible, les languages, et la réinstallation en cours (current) s'il y en a une.

{"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 droit reinstall

Tout le contenu du serveur est effacé. Sans password, un mot de passe est tiré au hasard et rendu une seule fois, dans cette réponse.

Champs pour un VPS : os_id (obligatoire), password (12 caractères ou plus).

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}'

Champs pour un serveur dédié :

Champ
osObligatoire : le code d'un système de GET …/reinstall.
hostnameObligatoire. 15 caractères au plus sous Windows.
language, timezoneObligatoires : une des languages, et un fuseau horaire comme Europe/Paris.
passwordFacultatif, 12 à 128 caractères, trois familles de caractères sur quatre.
ssh_keyClé publique facultative (Linux).
diskref du disque, obligatoire quand disk_choice vaut true.
raid1, data_disks, partitioningFacultatifs (Linux) : true, une liste de ref de disques, simple ou 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": "fr", "timezone": "Europe/Paris", "disk": "sda", "ssh_key": "ssh-ed25519 AAAA… moi@machine"}'
{"data": {"accepted": true, "password": "tiré-une-seule-fois",
  "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}}}

Suivez-la avec GET /services/{id}/reinstall (current) : status passe à installing puis ready, ou failed, cancelled, expired.

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

Serveurs dédiés, tant que cancellable vaut true (rien n'est encore écrit sur les disques).

Factures

GET/invoices

Les plus récentes d'abord. Pagination : page (à partir de 1) et per_page (20 par défaut, 100 au plus).

{"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. Un avis pas encore payé a un numéro qui commence par AE- ; il reçoit son numéro INV- au paiement.

GET/invoices/{number}

Les mêmes champs, plus les lignes items (name, description, quantity, unit_price, total, hors taxes).

GET/invoices/{number}/pdf

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

Catalogue

GET/catalog

Les produits que l'API peut commander (serveurs de jeu et VPS), avec le nombre d'offres en vente aujourd'hui.

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

GET/catalog/{type}

Les offres d'un produit avec leurs caractéristiques et leurs prix pour votre compte : excl_tax (hors taxes) et total, ce que vous payez, TVA comprise selon votre pays et votre statut. Aussi les durées et leur remise, les systèmes d'un VPS (os) et les options mensuelles. Les valeurs ci-dessous sont un exemple.

{"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": "Sauvegardes", "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}}}]}}

Commandes

Commandez un serveur de jeu ou un VPS payé avec le solde de votre compte (à alimenter depuis votre espace client). Prix, TVA, facture et livraison automatique sont les mêmes que pour une commande passée dans l'espace client. Demande le droit order.

POST/orders droit order

ChampValeur
typeLe produit, donné par GET /catalog.
offer_idL'offre, donnée par GET /catalog/{type}.
periodmonthly (par défaut), quarterly ou annually.
osSystème d'un VPS, pris dans le catalogue. Système par défaut s'il manque.
addonsFacultatif : numéros d'options, ou objets {"id": 12, "quantity": 2}.
dry_runBooléen JSON. true : rend le prix exact pour votre compte et votre solde, sans rien commander.

Tout autre champ est refusé (400 unknown_field), de même qu'un dry_run qui n'est pas un booléen JSON : une faute de frappe ne change jamais un devis en commande. Chaque vraie commande demande un en-tête Idempotency-Key (8 à 64 caractères : lettres, chiffres, - _ . :), différent pour chaque commande. Renvoyer la même clé (délai dépassé, erreur réseau) ne commande jamais deux fois : vous recevez la première réponse, avec Idempotent-Replayed: true. Une commande refusée avant toute création (solde trop bas, offre épuisée) libère sa clé : corrigez la cause et renvoyez-la.

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

201 : la facture payée et les services créés. Un service commence en pending : suivez-le avec GET /services/{id} jusqu'à active.

{"data": {
  "order": {"id": 42, "status": "paid", "idempotency_key": "commande-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
}}

Solde trop bas : 402 insufficient_balance, rien n'est créé. Les options payées une fois (prestations d'installation) ne se commandent pas par l'API. Votre pays doit être renseigné dans votre profil, il fixe la TVA : sinon 422 country_required.

GET/orders

Les commandes passées par l'API sur votre compte, de la plus récente à la plus ancienne (?page, ?per_page jusqu'à 100) : état, clé utilisée, produit, total, facture et services.

Une question, une fonction qui manque : ouvrez un ticket depuis votre espace client.