Erste Schritte
- Melde dich in deinem ServerPrism-Konto an.
- Öffne Benutzerkonto → API-Zugangsdaten und erstelle ein Token.
- Wähle die kleinstmögliche Auswahl an Scopes, die deine Integration braucht.
- Kopiere das Token einmalig, wenn es angezeigt wird: Wir speichern es nie im Klartext und können es nicht wiederherstellen.
- Verwende das Token als Bearer-Credential für die Endpunkte unten.
Alle Anfragen gehen an https://serverprism.com. Alle Antworten sind JSON. Alle Zeitstempel sind UTC im ISO-8601-Format.
Authentifizierung
Übergib das Token im Header Authorization: Bearer. Tokens sind persönlich: Jedes gehört genau einem ServerPrism-Kunden und kann nur auf Dienste dieses Kunden zugreifen.
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json"Tokens, die du im Dashboard erstellst, sind persönliche Zugriffstokens. Die OAuth-Abläufe Client Credentials und Authorization Code stehen für Kundenintegrationen derzeit nicht zur Verfügung.
Scopes
Jedes Token trägt einen oder mehrere Scopes. Ein Endpunkt verlangt einen bestimmten Scope: Fehlt er, kommt 403 zurück.
| Scope | Erlaubt |
|---|---|
servers:read |
Deine Server ansehen (Status, Ressourcen, Basisinfos) |
servers:control |
Power-Signale (Start/Stopp/Neustart/Kill) und Konsolenbefehle an deine Server senden |
backups:create |
Neue Backups deiner Server erstellen (zählt gegen deine Backup-Slots) |
billing:read |
Abrechnungsdetails deiner Dienste und deine Rechnungen ansehen (inklusive PDF-Download) |
tickets:read |
Deine Support-Tickets und deren Antworten ansehen |
tickets:write |
Neue Support-Tickets eröffnen und auf bestehende Tickets antworten |
account:read |
Deine grundlegenden Kontodaten ansehen (Name, E-Mail-Adresse) |
Rate Limits
Die Limits gelten pro Minute und zweifach: einmal pro Token und einmal über alle Tokens deines Kontos (es zählt, was zuerst aufgebraucht ist). Sie sind bewusst konservativ. Brauchst du mehr, eröffne ein Ticket und erzähl uns von deiner Integration.
| Bucket | Limit | Endpunkte |
|---|---|---|
read |
60 pro Token, 120 pro Konto | Alle GET-Endpunkte außer dem Rechnungs-PDF |
control |
20 pro Token, 30 pro Konto | Power, Befehl, Backup erstellen, Rechnungs-PDF |
tickets |
5 pro Token, 10 pro Konto; dazu 1 neues Ticket pro 30 Sekunden | Ticket eröffnen, auf Ticket antworten |
Wird ein Limit überschritten, kommt 429 Too Many Requests mit einem Retry-After-Header zurück. Jede Antwort enthält X-RateLimit-Limit und X-RateLimit-Remaining für den Token-Bucket. Warte ab und versuche es erneut; hämmere nie in einer engen Schleife auf einen 429 ein.
Fehler
Fehlerantworten sind JSON mit einer lesbaren message und bei API-spezifischen Fehlern einem stabilen, maschinenlesbaren error-Code wie service_not_active. Validierungsfehler (422) enthalten außerdem ein errors-Objekt, nach Feldern geordnet.
| Status | Bedeutung |
|---|---|
| 401 | Token fehlt oder ist ungültig. |
| 403 | Das Token enthält den erforderlichen Scope nicht. |
| 404 | Nicht gefunden oder gehört nicht dir (beides sieht absichtlich gleich aus). |
| 409 | Der Server befindet sich in einem Zustand, der das nicht erlaubt: service_not_active (gesperrt, gekündigt, ausstehend), service_paused (Kaltspeicher), server_offline, server_busy, backup_limit_reached, backup_in_progress. |
| 422 | Der Anfragekörper hat die Validierung nicht bestanden. |
| 429 | Rate Limit überschritten. |
| 503 | Der zugrunde liegende Knoten ist vorübergehend nicht erreichbar. Versuche es nach kurzer Pause erneut. |
Endpunkte
Die Server-ID in den URLs ist die numerische Dienst-ID, dieselbe wie in deiner URL /services/{id}. Alle Pfade unten gelten relativ zu https://serverprism.com/api/v1/client. Listen-Endpunkte akzeptieren page und per_page (max. 100) und liefern einen meta-Block mit total und last_page.
/api/v1/client/serversScope: servers:readListet jeden aktiven oder gesperrten Dienst des Token-Inhabers auf. Günstig abzufragen: Der Server wird dabei nicht kontaktiert.
Anfrage
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN"Antwort
{
"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:readAlles aus dem Listen-Endpunkt plus die Verbindungsadresse der Spieler, die Ports des Servers, seine Limits und eine bestmögliche Live-Ressourcennutzung.
Antwort
{
"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
}
}
}Der Block resources kann null sein, wenn der Knoten kurz nicht erreichbar war. Versuche es erneut oder nutze die Statusanzeige im Panel.
/api/v1/client/servers/{id}/powerScope: servers:controlSendet ein Power-Signal an den Server. Funktioniert nur, solange der Dienst aktiv ist: Gesperrte, gekündigte oder pausierte Dienste liefern 409.
Anfragekörper
{
"signal": "start" // one of: "start", "stop", "restart", "kill"
}kill beendet den Prozess hart, ohne dem Spiel Zeit zum Speichern zu geben. Nutze stop für ein sauberes Herunterfahren bei Spielen mit Spielstand.
Beispiel
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"}'Antwort
{ "data": { "signal": "restart", "sent": true } }/api/v1/client/servers/{id}/commandScope: servers:controlSendet einen einzelnen Konsolenbefehl an den laufenden Server (z. B. say hello, stop, whitelist add Notch). Der Server muss laufen; sonst erhältst du 409 server_offline.
Anfragekörper
{
"command": "say Server restarting in 5 minutes"
}Eine Zeile, höchstens 1024 Zeichen. Zeilenumbrüche und andere Steuerzeichen werden mit 422 abgelehnt: Sende pro Befehl eine Anfrage.
Antwort
{ "data": { "command": "say Server restarting in 5 minutes", "sent": true } }/api/v1/client/servers/{id}/backupsScope: servers:readListet die Backups des Servers und deine Backup-Slots auf. Die Slots werden von allen deinen Servern geteilt und wachsen mit dem RAM deines Tarifs.
Antwort
{
"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:createStartet ein Backup und gibt sofort 202 zurück. Backups laufen im Hintergrund: Frage den Listen-Endpunkt ab, bis status den Wert completed oder failed hat. Jedes Backup belegt einen Slot; sind keine Slots mehr frei, erhältst du 409 backup_limit_reached. Testtarife enthalten keine Backups (403). Backups wiederherstellen und löschen geht nur im Dashboard.
Anfragekörper (optional)
{ "name": "before-1.21-update" }Antwort (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:readAntwort
{ "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:readAlle deine Dienste in jedem Status, mit Abrechnungsdetails. Optionaler Filter ?status= mit einem von pending, provisioning, active, suspended, cancelled, failed.
Antwort
{
"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:readDeine Rechnungen, die neueste zuerst. Optionaler Filter ?status=pending|paid|cancelled.
Antwort
{
"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 }
}Um eine Rechnung zu bezahlen, öffne ihre dashboard_url. Die API bewegt nie Geld.
/api/v1/client/invoices/{id}Scope: billing:readDieselben Felder wie in der Liste plus die Positionen. {id} ist die numerische id, nicht die Rechnungsnummer.
Antwort (Auszug)
{
"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:readLädt die Rechnung als PDF (application/pdf) herunter, dasselbe Dokument wie die Download-Schaltfläche im Dashboard. Zählt gegen den Rate-Limit-Bucket control.
curl -o invoice.pdf https://serverprism.com/api/v1/client/invoices/5512/pdf \
-H "Authorization: Bearer YOUR_TOKEN"/api/v1/client/ticketsScope: tickets:readDeine Support-Tickets, zuletzt aktualisierte zuerst. Optionaler Filter ?status=open|replied|closed. replied bedeutet, unser Team hat geantwortet und wartet auf dich.
Antwort
{
"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:readDas Ticket samt Unterhaltung, älteste Nachricht zuerst. author ist you oder staff. Anhänge werden nur mit Namen aufgeführt; lade sie im Dashboard herunter.
Antwort (Auszug)
{
"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:writeEröffnet ein Ticket. department ist Pflicht und muss eine der Abteilungen sein, die das Formular für neue Tickets im Dashboard zeigt. priority ist low (Standard), medium oder high. service_id ist optional und muss einer deiner Dienste sein. Ein neues Ticket pro 30 Sekunden und Konto. Liefert 201 mit demselben Körper wie Ticket abrufen.
Anfragekörper
{
"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:writeFügt deine Antwort zu einem deiner Tickets hinzu (bis zu 20.000 Zeichen). Eine Antwort auf ein geschlossenes Ticket öffnet es wieder, genau wie im Dashboard. Liefert 201 mit der neuen Nachricht.
Anfragekörper
{ "message": "Still happening tonight, see the timings report." }Nicht über die API verfügbar
Absichtlich kann die API keine Dienste bezahlen, kündigen, hoch- oder herabstufen, keine Gutscheine einlösen, keine Backups löschen oder wiederherstellen und keine Dateien löschen. Diese Aktionen gibt es im Dashboard, wo du vor der Bestätigung genau siehst, was sie bewirken.
Versionierung
Der Namespace v1 ist stabil. Inkompatible Änderungen gibt es nur in einem neuen Namespace (v2); wir können bestehenden Antworten ohne Vorwarnung neue Felder hinzufügen, schreibe deinen Client also so, dass er unbekannte Schlüssel ignoriert.
Feature-Wünsche und Fehlermeldungen: Eröffne ein Ticket und erwähne "API".