Utiliser l'API : premiers appels et exemples

Vous avez un jeton (voir « Créer et gérer vos jetons d'API ») : voici comment l'utiliser. L'API répond en JSON, à l'adresse indiquée dans la page Mon profil › API, du type https://votre-espace-client/api/portal/v1.

S'identifier

Chaque appel porte le jeton dans l'en-tête Authorization :

curl -H "Authorization: Bearer mmcp_…" "https://votre-espace-client/api/portal/v1/services"

Cet appel, avec la portée de lecture, renvoie vos services et leur état.

Quelques exemples

Les factures (portée facturation) :

curl -H "Authorization: Bearer mmcp_…" "https://votre-espace-client/api/portal/v1/invoices"

Redémarrer une VM (portée actions sur les VM, et le droit correspondant chez l'auteur du jeton) :

curl -X POST -H "Authorization: Bearer mmcp_…" -H "Content-Type: application/json" \
  -d '{"action":"reboot"}' "https://votre-espace-client/api/portal/v1/services/vm:101/power"

Les actions possibles sont start, shutdown, reboot, stop et reset. Les services se désignent par la référence que renvoie GET /services, comme vm:101.

Marquer un déploiement sur un service (portée annotations), pour le voir ensuite sur sa chronologie et ses graphiques : POST /services/{ref}/annotations.

Réinstaller un VPS avec un script de démarrage (portée « Vos VPS : réinstallation et mode rescue ») : GET /services/{ref}/vps donne les systèmes de l'offre, GET /startup-scripts vos scripts, puis :

curl -X POST -H "Authorization: Bearer mmcp_…" -H "Content-Type: application/json" \
  -d '{"template":9000,"confirm":"vps-101","startupScriptId":"…"}' \
  "https://votre-espace-client/api/portal/v1/services/vm:101/vps/reinstall"

confirm est le nom du VPS : la réinstallation efface son disque. Le mode rescue se pilote de la même façon, avec POST puis DELETE /services/{ref}/vps/rescue.

Mettre un serveur sur un réseau privé (portée « Réseaux privés entre vos serveurs ») : POST /private-networks crée le réseau, puis POST /private-networks/{id}/members avec {"ref":"vm:101"} y attache un serveur.

Ces appels n'existent que si la fonction correspondante est ouverte pour votre compte ; sinon l'API répond 404. Un jeton créé avant leur arrivée ne les gagne pas : chacun a sa propre portée, à cocher sur un nouveau jeton.

La liste complète

L'onglet Points d'accès de la page API liste chaque appel avec sa méthode, son chemin, la portée requise et ce qu'il fait. Filtrez par portée ou cherchez un mot, puis cliquez sur l'icône Copier la commande curl : la commande est prête, il ne reste qu'à mettre votre jeton et la référence voulue. Le lien OpenAPI donne la description complète, à importer dans Postman ou dans un générateur de client.

Limites et erreurs

• 120 requêtes par minute au plus et par jeton. Au-delà, l'API répond 429 : ralentissez.
• 401 : jeton absent, révoqué ou expiré, ou son auteur n'a plus accès à l'espace client.
• 403 : le jeton n'a pas la portée de cet appel, ou l'adresse IP d'où vous appelez n'est pas autorisée par votre société.
• 404 : la ressource n'existe pas, ou n'appartient pas à votre société.

Bon à savoir

• Un jeton n'ouvre que l'API : il ne permet pas de se connecter à l'espace client.
• Les métriques au format Prometheus ont leur propre jeton, sur la même page, carte Métriques Prometheus.