Premiers pas
- Connectez-vous à votre compte ServerPrism.
- Ouvrez Compte → Identifiants API et créez un jeton.
- Choisissez le plus petit ensemble de scopes dont votre intégration a besoin.
- 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.
- 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 |
|---|---|
| 401 | Jeton manquant ou invalide. |
| 403 | Le jeton n'inclut pas le scope requis. |
| 404 | Introuvable, ou ne vous appartient pas (les deux cas se ressemblent volontairement). |
| 409 | Le 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. |
| 422 | Le corps de la requête n'a pas passé la validation. |
| 429 | Limite de débit dépassée. |
| 503 | Le 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.
/api/v1/client/serversscope : servers:readListe 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"
}
]
}/api/v1/client/servers/{id}scope : servers:readTout 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.
/api/v1/client/servers/{id}/powerscope : servers:controlEnvoie 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 } }/api/v1/client/servers/{id}/commandscope : servers:controlEnvoie 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 } }/api/v1/client/servers/{id}/backupsscope : servers:readListe 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 } }
}/api/v1/client/servers/{id}/backupsscope : backups:createLance 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 } }/api/v1/client/accountscope : account:readRé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" } }/api/v1/client/servicesscope : billing:readTous 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 }
}/api/v1/client/invoicesscope : billing:readVos 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.
/api/v1/client/invoices/{id}scope : billing:readLes 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 }
]
}
}/api/v1/client/invoices/{id}/pdfscope : billing:readTé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"/api/v1/client/ticketsscope : tickets:readVos 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 }
}/api/v1/client/tickets/{id}scope : tickets:readLe 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" }
]
}
}/api/v1/client/ticketsscope : tickets:writeOuvre 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
}/api/v1/client/tickets/{id}/messagesscope : tickets:writeAjoute 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 ».