Black Friday : 25 % de réduction à vie sur les nouveaux serveurs avec le code .Voir les offres

ServerPrism API

Pilotez vos serveurs par programme (état, alimentation, commandes console, sauvegardes) et lisez vos factures et vos tickets de support depuis vos propres scripts, tableaux de bord et bots.

Vous utilisez Claude, Cursor, VS Code ou un autre assistant IA ? Connectez-le à notre serveur MCP : même jeton, aucun code.

Les chemins des endpoints, les noms de champs, les codes de statut et les exemples de code sont affichés tels que votre code les voit : ils restent donc en anglais dans toutes les langues.

Sur cette page

Premiers pas

  1. Connectez-vous à votre compte ServerPrism.
  2. Ouvrez Compte → Identifiants API et créez un jeton.
  3. Choisissez le plus petit ensemble de scopes dont votre intégration a besoin.
  4. Copiez le jeton une seule fois quand il s'affiche : nous ne le stockons jamais en clair et ne pouvons pas le récupérer.
  5. Utilisez le jeton comme identifiant Bearer pour les endpoints ci-dessous.

Toutes les requêtes vont à https://serverprism.com. Toutes les réponses sont en JSON. Tous les horodatages sont en UTC au format ISO-8601.

Authentification

Transmettez le jeton dans un en-tête Authorization: Bearer. Les jetons sont personnels : chacun appartient à un seul client ServerPrism et ne peut agir que sur les services de ce client.

curl https://serverprism.com/api/v1/client/servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Les jetons que vous créez depuis le tableau de bord sont des jetons d'accès personnels. Les flux OAuth « client credentials » et « authorization code » ne sont pas proposés pour l'instant aux intégrations clients.

Scopes

Chaque jeton porte un ou plusieurs scopes. Un endpoint exige un scope précis : s'il manque, la réponse est 403.

Scope Autorise
servers:read Voir vos serveurs (état, ressources, infos de base)
servers:control Envoyer des signaux d'alimentation (démarrer/arrêter/redémarrer/kill) et des commandes console à vos serveurs
backups:create Créer de nouvelles sauvegardes de vos serveurs (elles comptent dans vos emplacements de sauvegarde)
billing:read Voir les détails de facturation de vos services et vos factures (téléchargement PDF compris)
tickets:read Voir vos tickets de support et leurs réponses
tickets:write Ouvrir de nouveaux tickets de support et répondre à vos tickets existants
account:read Voir les informations de base de votre compte (nom, adresse e-mail)

Limites de débit

Les limites s'appliquent par minute et deux fois : une fois par jeton et une fois sur l'ensemble des jetons de votre compte (la première atteinte compte). Elles sont volontairement prudentes. Si vous en avez besoin de plus, ouvrez un ticket et parlez-nous de votre intégration.

Bucket Limite Endpoints
read 60 par jeton, 120 par compte Tous les endpoints GET sauf le PDF de la facture
control 20 par jeton, 30 par compte Alimentation, commande, création de sauvegarde, PDF de la facture
tickets 5 par jeton, 10 par compte ; plus 1 nouveau ticket toutes les 30 secondes Ouvrir un ticket, répondre à un ticket

Dépasser une limite renvoie 429 Too Many Requests avec un en-tête Retry-After. Chaque réponse contient X-RateLimit-Limit et X-RateLimit-Remaining pour le bucket du jeton. Patientez puis réessayez ; ne bouclez jamais sans pause sur un 429.

Erreurs

Les corps d'erreur sont en JSON avec un message lisible et, pour les erreurs propres à l'API, un code error stable et lisible par machine, comme service_not_active. Les erreurs de validation (422) incluent aussi un objet errors classé par champ.

Statut Signification
401Jeton manquant ou invalide.
403Le jeton n'inclut pas le scope requis.
404Introuvable, ou ne vous appartient pas (les deux cas se ressemblent volontairement).
409Le serveur est dans un état qui ne le permet pas : service_not_active (suspendu, annulé, en attente), service_paused (stockage à froid), server_offline, server_busy, backup_limit_reached, backup_in_progress.
422Le corps de la requête n'a pas passé la validation.
429Limite de débit dépassée.
503Le nœud en amont est momentanément indisponible. Réessayez après une courte pause.

Endpoints

L'ID du serveur dans les URL est l'ID numérique du service, le même que dans votre URL /services/{id}. Tous les chemins ci-dessous sont relatifs à https://serverprism.com/api/v1/client. Les endpoints de liste acceptent page et per_page (100 max.) et renvoient un bloc meta avec total et last_page.

Lister les serveurs
GET/api/v1/client/serversscope : servers:read

Liste tous les services actifs ou suspendus du titulaire du jeton. Peu coûteux à interroger : le serveur n'est pas contacté.

Requête

curl https://serverprism.com/api/v1/client/servers \
  -H "Authorization: Bearer YOUR_TOKEN"

Réponse

{
  "data": [
    {
      "id": 1234,
      "product": "Minecraft 4 GB",
      "service_status": "active",
      "name": "Fred's Minecraft",
      "paused": false,
      "game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
      "expires_at": "2026-11-01T00:00:00+00:00"
    }
  ]
}
Obtenir un serveur
GET/api/v1/client/servers/{id}scope : servers:read

Tout ce que renvoie l'endpoint de liste, plus l'adresse de connexion des joueurs, les ports du serveur, ses limites et l'utilisation des ressources en direct (au mieux).

Réponse

{
  "data": {
    "id": 1234,
    "name": "Fred's Minecraft",
    "service_status": "active",
    "paused": false,
    "game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
    "expires_at": "2026-11-01T00:00:00+00:00",
    "address": "fredcraft.example.com",
    "allocations": [
      { "ip": "203.0.113.7", "port": 25565, "primary": true, "notes": null }
    ],
    "limits": {
      "memory_mb": 4096,
      "disk_mb": 25600,
      "cpu_percent": 200
    },
    "resources": {
      "current_state": "running",
      "memory_bytes": 2147483648,
      "cpu_absolute": 18.5,
      "disk_bytes": 7300000000,
      "network_rx_bytes": 12345678,
      "network_tx_bytes": 87654321,
      "uptime_ms": 3600000
    }
  }
}

Le bloc resources peut valoir null si le nœud était brièvement injoignable. Réessayez ou servez-vous de l'indicateur d'état du panneau.

Signal d'alimentation
POST/api/v1/client/servers/{id}/powerscope : servers:control

Envoie un signal d'alimentation au serveur. Ne fonctionne que si le service est actif : les services suspendus, annulés ou en pause renvoient 409.

Corps de la requête

{
  "signal": "start"   // one of: "start", "stop", "restart", "kill"
}

kill interrompt brutalement le processus sans laisser au jeu le temps de sauvegarder. Utilisez stop pour un arrêt propre des jeux avec sauvegarde de partie.

Exemple

curl -X POST https://serverprism.com/api/v1/client/servers/1234/power \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal":"restart"}'

Réponse

{ "data": { "signal": "restart", "sent": true } }
Envoyer une commande
POST/api/v1/client/servers/{id}/commandscope : servers:control

Envoie une seule commande console au serveur en marche (p. ex. say hello, stop, whitelist add Notch). Le serveur doit être démarré ; sinon vous obtenez 409 server_offline.

Corps de la requête

{
  "command": "say Server restarting in 5 minutes"
}

Une ligne, 1024 caractères au maximum. Les retours à la ligne et autres caractères de contrôle sont rejetés avec 422 : envoyez une requête par commande.

Réponse

{ "data": { "command": "say Server restarting in 5 minutes", "sent": true } }
Lister les sauvegardes
GET/api/v1/client/servers/{id}/backupsscope : servers:read

Liste les sauvegardes du serveur et vos emplacements de sauvegarde. Les emplacements sont partagés entre tous vos serveurs et suivent la RAM de votre offre.

Réponse

{
  "data": [
    {
      "uuid": "6f1c0e2a-...",
      "name": "nightly",
      "status": "completed",      // "in_progress" | "completed" | "failed"
      "size_bytes": 734003200,
      "locked": false,
      "created_at": "2026-09-30T03:00:00+00:00",
      "completed_at": "2026-09-30T03:04:12+00:00"
    }
  ],
  "meta": { "quota": { "used": 2, "total": 3, "can_create_more": true, "is_trial": false } }
}
Créer une sauvegarde
POST/api/v1/client/servers/{id}/backupsscope : backups:create

Lance une sauvegarde et renvoie 202 aussitôt. Les sauvegardes s'exécutent en arrière-plan : interrogez l'endpoint de liste jusqu'à ce que status vaille completed ou failed. Chaque sauvegarde occupe un emplacement ; quand il n'en reste plus, vous obtenez 409 backup_limit_reached. Les offres d'essai n'incluent pas de sauvegardes (403). Restaurer et supprimer des sauvegardes n'est possible que depuis le tableau de bord.

Corps de la requête (facultatif)

{ "name": "before-1.21-update" }

Réponse (202)

{ "data": { "uuid": "9a2b...", "name": "before-1.21-update", "status": "in_progress", "size_bytes": 0, "locked": false, "created_at": "2026-10-01T12:00:00+00:00", "completed_at": null } }
Compte
GET/api/v1/client/accountscope : account:read

Réponse

{ "data": { "id": 42, "first_name": "Fred", "last_name": "Smith", "email": "fred@example.com", "email_verified": true, "created_at": "2025-03-01T10:00:00+00:00" } }
Services (facturation)
GET/api/v1/client/servicesscope : billing:read

Tous vos services, quel que soit leur statut, avec les détails de facturation. Filtre facultatif ?status= parmi pending, provisioning, active, suspended, cancelled, failed.

Réponse

{
  "data": [
    {
      "id": 1234,
      "name": "Fred's Minecraft",
      "product": "Minecraft 4 GB",
      "status": "active",
      "paused": false,
      "plan": { "name": "Monthly", "type": "recurring", "billing_period": 1, "billing_unit": "month" },
      "quantity": 1,
      "price": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "next_due_date": "2026-11-01T00:00:00+00:00",
      "cancellation_requested": false,
      "cancellation_type": null,
      "created_at": "2026-05-01T09:12:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}
Lister les factures
GET/api/v1/client/invoicesscope : billing:read

Vos factures, les plus récentes d'abord. Filtre facultatif ?status=pending|paid|cancelled.

Réponse

{
  "data": [
    {
      "id": 5512,
      "number": "SP-2026-05512",
      "status": "pending",
      "currency": "EUR",
      "total": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "tax": { "amount": "1.60", "currency": "EUR", "formatted": "€1.60" },
      "remaining": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "due_at": "2026-10-04T00:00:00+00:00",
      "created_at": "2026-09-27T00:00:00+00:00",
      "pdf_url": "https://serverprism.com/api/v1/client/invoices/5512/pdf",
      "dashboard_url": "https://serverprism.com/invoices/SP-2026-05512"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}

Pour payer une facture, ouvrez sa dashboard_url. L'API ne déplace jamais d'argent.

Obtenir une facture
GET/api/v1/client/invoices/{id}scope : billing:read

Les mêmes champs que la liste, plus les lignes de la facture. {id} est l'id numérique, pas le numéro de facture.

Réponse (extrait)

{
  "data": {
    "id": 5512,
    "status": "pending",
    "items": [
      { "description": "Minecraft 4 GB (Oct 01, 2026 - Nov 01, 2026)", "quantity": 1, "unit_price": "8.00", "total": "8.00", "service_id": 1234 }
    ]
  }
}
PDF de la facture
GET/api/v1/client/invoices/{id}/pdfscope : billing:read

Télécharge la facture en PDF (application/pdf), le même document que le bouton de téléchargement du tableau de bord. Compte dans le bucket de limite control.

curl -o invoice.pdf https://serverprism.com/api/v1/client/invoices/5512/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"
Lister les tickets
GET/api/v1/client/ticketsscope : tickets:read

Vos tickets de support, les plus récemment mis à jour d'abord. Filtre facultatif ?status=open|replied|closed. replied signifie que notre équipe a répondu et attend votre retour.

Réponse

{
  "data": [
    {
      "id": 1301,
      "subject": "Server lagging in the evening",
      "status": "replied",
      "priority": "medium",
      "department": "Support",
      "service_id": 1234,
      "messages_count": 3,
      "last_message_at": "2026-10-01T09:30:00+00:00",
      "created_at": "2026-09-30T18:02:00+00:00",
      "updated_at": "2026-10-01T09:30:00+00:00",
      "dashboard_url": "https://serverprism.com/tickets/1301"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}
Obtenir un ticket
GET/api/v1/client/tickets/{id}scope : tickets:read

Le ticket et sa conversation, le message le plus ancien d'abord. author vaut you ou staff. Les pièces jointes sont listées par nom ; téléchargez-les depuis le tableau de bord.

Réponse (extrait)

{
  "data": {
    "id": 1301,
    "status": "replied",
    "messages": [
      { "id": 9001, "author": "you", "author_name": "Fred Smith", "message": "TPS drops every evening", "attachments": [], "created_at": "2026-09-30T18:02:00+00:00" },
      { "id": 9007, "author": "staff", "author_name": "ServerPrism Support", "message": "We moved you to a quieter host...", "attachments": [], "created_at": "2026-10-01T09:30:00+00:00" }
    ]
  }
}
Ouvrir un ticket
POST/api/v1/client/ticketsscope : tickets:write

Ouvre un ticket. department est obligatoire et doit être l'un des services affichés dans le formulaire de nouveau ticket du tableau de bord. priority vaut low (par défaut), medium ou high. service_id est facultatif et doit être l'un de vos services. Un nouveau ticket toutes les 30 secondes par compte. Renvoie 201 avec le même corps que Obtenir un ticket.

Corps de la requête

{
  "subject": "Server lagging in the evening",
  "message": "TPS drops to ~12 between 19:00 and 22:00 CET.",
  "department": "Support",
  "priority": "medium",
  "service_id": 1234
}
Répondre à un ticket
POST/api/v1/client/tickets/{id}/messagesscope : tickets:write

Ajoute votre réponse à l'un de vos tickets (jusqu'à 20 000 caractères). Répondre à un ticket fermé le rouvre, comme dans le tableau de bord. Renvoie 201 avec le nouveau message.

Corps de la requête

{ "message": "Still happening tonight, see the timings report." }

Non disponible via l'API

Volontairement, l'API ne peut ni payer, ni annuler, ni faire évoluer vos services à la hausse ou à la baisse, ni appliquer de coupons, ni supprimer ou restaurer des sauvegardes, ni supprimer des fichiers. Ces actions se font dans le tableau de bord, où vous voyez exactement ce qu'elles feront avant de confirmer.

Versions

L'espace de noms v1 est stable. Les changements incompatibles n'arriveront que dans un nouvel espace de noms (v2) ; nous pouvons ajouter de nouveaux champs aux réponses existantes sans préavis, écrivez donc votre client de façon à ignorer les clés inconnues.

Demandes de fonctionnalités et rapports de bogues : ouvrez un ticket et mentionnez « API ».