API Reference — V1

Vollständige Referenz der Mado Hosting Reseller API. Verwalte Server, Backups, Dateien und mehr programmatisch.

Base URL

https://www.mado-hosting.com/api/v1

Authentifizierung

Alle API-Anfragen müssen einen gültigen API-Key im Authorization-Header enthalten. API-Keys beginnen mit dem Prefix rsk_ und können im Reseller Dashboard erstellt werden.

curl -X GET "https://www.mado-hosting.com/api/v1/servers" \
  -H "Authorization: Bearer rsk_your_api_key_here" \
  -H "Content-Type: application/json"

Antwortformat

Alle erfolgreichen Antworten folgen einem einheitlichen Format mit einem data-Objekt. Paginierte Endpunkte enthalten zusätzlich ein pagination-Objekt.

Erfolg

{
  "data": {
    "servers": [...]
  }
}

Fehler

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "requestId": "req_abc123"
  }
}

Paginierung

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 48,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  }
}

Headers

Header	Beschreibung
`Authorization`	Pflicht. Bearer Token mit API-Key. `Bearer rsk_...`
`Content-Type`	Pflicht für POST/PUT/PATCH. `application/json`
`X-Request-Id`	Antwort-Header. Eindeutige Request-ID für Debugging.
`Idempotency-Key`	Optional. Verhindert doppelte Ausführung (24h Cache).
`If-Match`	Optimistic Locking für PATCH /servers/[id]. Version-Nummer übergeben.
`X-RateLimit-Limit`	Antwort. Maximale Anfragen pro Zeitfenster.
`X-RateLimit-Remaining`	Antwort. Verbleibende Anfragen im aktuellen Zeitfenster.

Fehlercodes

Alle Fehler folgen dem gleichen Format mit einem maschinenlesbaren code und einer menschenlesbaren message.

HTTP	Code	Beschreibung
400	`VALIDATION_ERROR`	Ungültige Parameter oder fehlende Pflichtfelder
400	`LIMIT_EXCEEDED`	Quota-/Ressourcen-Limit erreicht (Backups, Schedules, etc.)
400	`NO_CHANGE`	Resize auf gleiche Größe
400	`INVALID_RAM`	RAM nicht in gültigen Schritten (0.5GB)
400	`BELOW_MIN_RAM`	RAM unter Pricing-Minimum
400	`ABOVE_MAX_RAM`	RAM über Pricing-Maximum
400	`RAM_LIMIT_EXCEEDED`	Gesamt-RAM des Resellers überschritten
400	`DISK_USAGE_EXCEEDED`	Downgrade nicht möglich wegen Disk-Nutzung
401	`AUTH_REQUIRED`	Fehlender oder ungültiger API-Key
403	`FORBIDDEN`	Unzureichende Berechtigungen
403	`ADDON_REQUIRED`	Feature benötigt ein Addon oder Premium Plan
403	`FEATURE_UNAVAILABLE`	Feature nicht verfügbar für diesen Plan
403	`DISTRIBUTION_RESTRICTED`	Mod erlaubt keinen 3rd-Party Download
404	`SERVER_NOT_FOUND`	Server nicht gefunden oder gehört nicht zum Reseller
404	`USER_NOT_FOUND`	Benutzer nicht gefunden (Subuser)
404	`NOT_FOUND`	Ressource auf Pelican-Ebene nicht gefunden
409	`CONFLICT`	Versions-Mismatch oder Duplikat
409	`SERVER_SUSPENDED`	Server ist gesperrt — Schreibzugriff blockiert
409	`SERVER_INSTALLING`	Server wird noch eingerichtet
409	`ALREADY_EXISTS`	Entität existiert bereits (z.B. Subuser)
422	`LIMIT_REACHED`	Pelican-seitiges Limit erreicht
500	`CONFIG_ERROR`	Server-Konfiguration fehlt (z.B. DB-Host)
500	`INTERNAL_ERROR`	Interner Serverfehler
500	`UPLOAD_FAILED`	Mod-Upload zum Server fehlgeschlagen
503	`SERVICE_UNAVAILABLE`	Keine verfügbaren Nodes, Ports oder Panel nicht erreichbar