Mit der Agentur-API liest du deine Kunden, den Plugin-Bestand, die Lizenzübersicht und die Wartungsberichte deiner Websites automatisiert aus, zum Beispiel für ein eigenes Dashboard. Du kannst außerdem Kunden pflegen, Arbeitszeit aus deiner Zeiterfassung eintragen und Berichte an deine Kunden senden. Alles, was du per API änderst, ändert dasselbe wie im Panel und ist dort sofort zu sehen.
Voraussetzungen
- Dein Konto hat im WP-Cockpit die Seite „Kunden & Websites“ (Agentur-Funktion).
- Du bist im Kundenkonto angemeldet und darfst die betreffenden Hostingverträge verwalten.
- Die Daten stammen aus den Tagesberichten und der letzten Plugin-Lesung des Cockpits. Sie sind kein Live-Messwert; jede Antwort nennt den Stand (
as_of).
API-Schlüssel „Agentur: lesen“ anlegen
- Öffne im Panel über dein Konto-Menü API & KI-Zugriff.
- Wähle die Schnellauswahl Agentur: lesen (angehakt werden
sites:read,clients:read,plugins:read,reports:read,updates:readundbackups:read). - Wähle das Ziel: Ganzes Konto für alle Websites oder Ein Kunde für die Websites eines Kunden. Beide Ziele gelten auch für Websites, die später dazukommen bzw. diesem Kunden zugeordnet werden. Bei Ausgewählte Websites werden die Agentur-Schnellauswahlen ausgeblendet und
clients:readist nicht möglich;plugins:readkannst du dort einzeln wählen, es gilt dann nur für die gewählten Websites. - Vergib einen Namen, wähle den Ablauf und kopiere das einmal angezeigte Secret in deinen Secret Store.
Weitere API-Schlüssel für Schreibzugriffe
Für Änderungen legst du einen eigenen API-Schlüssel (in der Technik auch Token genannt) an (API & KI-Zugriff, Ziel Ganzes Konto oder Ein Kunde; Lizenzangaben pflegen geht nur mit Ganzes Konto):
- Zeiterfassung (Schnellauswahl):
clients:readundwork:write. Damit trägt dein Zeiterfassungssystem Arbeitszeit ein und löscht sie wieder. - Kunden anlegen, ändern oder löschen (
clients:write), Lizenzangaben pflegen (licenses:write), Links zu Berichten erzeugen (reports:share) und Berichte senden (reports:send) stehen in keiner Schnellauswahl; hake sie einzeln an (Bereich Agentur oder über das Suchfeld). Vergib sie nur an API-Schlüssel, die sie brauchen. Das Löschen eines Kunden entfernt auch sein Arbeitslog und seine Berichte. - Zum Schreiben brauchst du im Konto das Recht, Hosting zu ändern.
Abfragen
export TP_API_TOKEN='tpapi_…' # besser aus dem Secret Store lesen
curl -sS -H "Authorization: Bearer $TP_API_TOKEN" https://panel.turbopress.de/api/v1/clients
curl -sS -H "Authorization: Bearer $TP_API_TOKEN" 'https://panel.turbopress.de/api/v1/plugins?state=update'
curl -sS -H "Authorization: Bearer $TP_API_TOKEN" https://panel.turbopress.de/api/v1/licenses
curl -sS -H "Authorization: Bearer $TP_API_TOKEN" 'https://panel.turbopress.de/api/v1/sites?client_id=12'
GET /clientslistet deine Kunden mit Websiteanzahl, Kontingent und Preis;GET /clients/{client_id}ergänzt die Websites und die Arbeitszeit des laufenden Monats.GET /pluginszeigt jedes Plugin einmal über alle Websites: Versionen, offene Updates, bekannte Sicherheitslücken.GET /plugins/{slug}zeigt, auf welchen Websites es läuft.GET /licensesfasst die Lizenzlage je Plugin zusammen. Lizenzschlüssel gibt die API nie aus.- Antworten mit vielen Einträgen kommen seitenweise (
meta.next_cursor). Für einen vollständigen Abgleich beginne immer bei Seite 1.
Arbeitszeit aus der Zeiterfassung eintragen
Lege einen API-Schlüssel mit der Schnellauswahl Zeiterfassung an. Jeder Eintrag bekommt von dir eine eigene ID (external_id), zum Beispiel die Nummer des Zeitbuchs in deinem System. So kannst du denselben Import gefahrlos wiederholen: kommt dieselbe external_id ein zweites Mal, lehnt die API den Eintrag mit 409 duplicate_entry ab und nennt in existing_id den vorhandenen Eintrag, sofern er zum selben Kunden gehört.
curl -sS -X POST https://panel.turbopress.de/api/v1/clients/12/work-entries \
-H "Authorization: Bearer $TP_API_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"date": "2026-10-28", "minutes": 45, "text": "Plugin-Updates und Test", "site_id": "site_abc123", "external_id": "zeit-2026-10-28-001"}'
dateist ein Tag der letzten zwei Jahre, nicht in der Zukunft.minutesliegt zwischen 5 und 1440,texthat höchstens 280 Zeichen,external_idhöchstens 100 Zeichen ohne Leerzeichen.site_idist optional und muss zu den Websites deines API-Schlüssels gehören.- Den
Idempotency-Keybrauchst du bei jedem Schreibzugriff. Erzeuge pro Eintrag einen neuen Schlüssel und nimm bei einer Wiederholung nach einem Timeout denselben noch einmal: die API liefert dann die gespeicherte Antwort, statt doppelt zu buchen. GET /clients/12/work-entries?month=2026-10zeigt die Einträge eines Monats mit Summe und Kontingent. MitDELETE /clients/12/work-entries/{id}löschst du einen Eintrag (Antwort204).- Es gelten höchstens 30 Schreibzugriffe pro Minute und Konto. Bei
429wartest du die Sekunden ausRetry-Afterab.
Bericht senden
Mit einem API-Schlüssel, der reports:read und reports:send trägt, liest du den Bericht eines abgeschlossenen Zeitraums und sendest ihn an deinen Kunden. Die Zeiträume (period, z. B. 2026-09 oder 2026Q3) liefert GET /clients/12/reports.
curl -sS -H "Authorization: Bearer $TP_API_TOKEN" https://panel.turbopress.de/api/v1/clients/12/reports/2026-09
curl -sS -X POST https://panel.turbopress.de/api/v1/clients/12/reports/2026-09/send \
-H "Authorization: Bearer $TP_API_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" -d '{}'
- Der Bericht enthält genau das, was auch dein Panel, der Link und die Mail zeigen. Was du dort ausgeblendet hast, fehlt in der API-Antwort; Rohzahlen gibt es nicht.
- Die Mail geht an die Adresse, die du beim Kunden hinterlegt hast, und wird sofort gesendet. Die Antwort nennt Zeitpunkt (UTC) und Adresse.
- Ein schon gesendeter Bericht antwortet
409 already_sent. Mit{"resend": true}sendest du ihn erneut, frühestens 5 Minuten nach dem letzten Senden und höchstens 3 Mal je Zeitraum und Kunde (danach429 resend_limitohneRetry-After: das ist endgültig). - Gesendet werden nur abgeschlossene Zeiträume der letzten 12 Monate (
422 period_not_sendable), und der Kunde braucht eine gültige Mail-Adresse (422 client_email_missing). - Anders als der Monatslauf prüft das Senden per API nicht die Schalter „Bericht senden“ und „Wartungsvertrag“ des Kunden. Wie der Knopf im Panel sendet es immer, wenn du es auslöst.
- Scheitert die Mail (
502 send_failed), ist nichts als gesendet markiert. Wiederhole mit demselben Schlüssel. POST /clients/12/reports/2026-09/share-linkserzeugt einen Link zum Bericht ohne Login, 90 Tage gültig. Die Adresse steht nur in dieser einen Antwort; speichere sie sofort. Wiederholst du denselben Schlüssel, bekommst du409 secret_not_replayableund keinen zweiten Link. Für einen neuen Link nimmst du einen neuen Schlüssel.
Gut zu wissen
- Themes sind nicht im Plugin-Bestand.
- Eine neu angelegte Website kann einige Minuten brauchen, bis sie in
GET /siteserscheint. - Ein API-Schlüssel mit dem Ziel „Ausgewählte Websites“ kann keine Kundendaten lesen (
clients:read); Plugins und Lizenzen sieht er nur für die gewählten Websites. Lege für Kundendaten einen API-Schlüssel mit Ziel „Ein Kunde“ oder „Ganzes Konto“ an. - Ein API-Schlüssel mit Kundenziel sieht und ändert nur diesen einen Kunden. Websites kann er nur vom Kunden lösen, nicht anderen Kunden zuordnen.
- Dein Kunde „Eigene Sites“ hat keine Berichte und lässt sich nicht löschen.
- Die Änderungen erscheinen mit Kanal
apiim Aktivitätsprotokoll deines Kontos.
Typische Probleme
- **403
feature_not_enabled:** Für dein Konto ist „Kunden & Websites“ nicht aktiv. Wende dich an den Support. - **503
feature_unavailable:** Die Agentur-API ist derzeit nicht verfügbar. Später erneut versuchen. - **404
client_not_found/plugin_not_found:** ID bzw. Slug prüfen. - **400
invalid_idempotency_key:** Bei jedem Schreibzugriff, auchPATCHundPUT, ist der HeaderIdempotency-KeyPflicht (16 bis 128 Zeichen). - **400
invalid_arguments:**error.fieldnennt das Feld, das nicht stimmt. - **409
idempotency_unknown:** Der Ausgang des ersten Versuchs ist unklar. Prüfe den Zustand mit einer Leseroute, bevor du mit einem neuen Schlüssel wiederholst. - **Website fehlt oder
site_idistnull:** Die Website ist noch nicht erfasst; sie erscheint nach dem nächsten Abruf vonGET /sites.
Weitere Anleitungen
API-Schlüssel erstellen und widerrufen · OpenAPI-Referenz · Fehler und Timeouts