Black Friday: 25 % Rabatt auf Lebenszeit für neue Server mit dem Code .Pakete ansehen

ServerPrism API

Steuere deine Server per Code (Status, Power, Konsolenbefehle, Backups) und lies deine Rechnungen und Support-Tickets aus eigenen Skripten, Dashboards und Bots.

Du nutzt Claude, Cursor, VS Code oder einen anderen KI-Assistenten? Verbinde ihn mit unserem MCP-Server: gleiches Token, kein Code.

Endpunkt-Pfade, Feldnamen, Statuscodes und Codebeispiele stehen so da, wie dein Code sie sieht, und bleiben deshalb in jeder Sprache auf Englisch.

Auf dieser Seite

Erste Schritte

  1. Melde dich in deinem ServerPrism-Konto an.
  2. Öffne Benutzerkonto → API-Zugangsdaten und erstelle ein Token.
  3. Wähle die kleinstmögliche Auswahl an Scopes, die deine Integration braucht.
  4. Kopiere das Token einmalig, wenn es angezeigt wird: Wir speichern es nie im Klartext und können es nicht wiederherstellen.
  5. 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
401Token fehlt oder ist ungültig.
403Das Token enthält den erforderlichen Scope nicht.
404Nicht gefunden oder gehört nicht dir (beides sieht absichtlich gleich aus).
409Der 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.
422Der Anfragekörper hat die Validierung nicht bestanden.
429Rate Limit überschritten.
503Der 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.

Server auflisten
GET/api/v1/client/serversScope: servers:read

Listet 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"
    }
  ]
}
Server abrufen
GET/api/v1/client/servers/{id}Scope: servers:read

Alles 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.

Power-Signal
POST/api/v1/client/servers/{id}/powerScope: servers:control

Sendet 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 } }
Befehl senden
POST/api/v1/client/servers/{id}/commandScope: servers:control

Sendet 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 } }
Backups auflisten
GET/api/v1/client/servers/{id}/backupsScope: servers:read

Listet 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 } }
}
Backup erstellen
POST/api/v1/client/servers/{id}/backupsScope: backups:create

Startet 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 } }
Konto
GET/api/v1/client/accountScope: account:read

Antwort

{ "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" } }
Dienste (Abrechnung)
GET/api/v1/client/servicesScope: billing:read

Alle 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 }
}
Rechnungen auflisten
GET/api/v1/client/invoicesScope: billing:read

Deine 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.

Rechnung abrufen
GET/api/v1/client/invoices/{id}Scope: billing:read

Dieselben 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 }
    ]
  }
}
Rechnungs-PDF
GET/api/v1/client/invoices/{id}/pdfScope: billing:read

Lä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"
Tickets auflisten
GET/api/v1/client/ticketsScope: tickets:read

Deine 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 }
}
Ticket abrufen
GET/api/v1/client/tickets/{id}Scope: tickets:read

Das 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" }
    ]
  }
}
Ticket eröffnen
POST/api/v1/client/ticketsScope: tickets:write

Erö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
}
Auf Ticket antworten
POST/api/v1/client/tickets/{id}/messagesScope: tickets:write

Fü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".