REST-API-Übersicht

Mit der REST-API liest und ändert Ihr eigener Code Ihre Daten in plnnrly: Projekte, Arbeitselemente, Stunden, Drive-Dokumente, Kunden, Rechnungen, Abwesenheiten, Planung und mehr. Sie arbeitet mit JSON über HTTPS, auf der eigenen plnnrly-Adresse Ihrer Organisation.

Die API-Anleitungen und die Referenz sind auf Englisch. Diese Seite fasst das Wichtigste auf Deutsch zusammen und verlinkt an den passenden Stellen dorthin.

Verbindungsdaten

Einstellung	Wert
Basis-URL	`https://<ihre-url>/api/v2`
Authentifizierung	`Authorization: Bearer <token>`
Format	JSON. Senden Sie bei jeder Anfrage mit Body `Content-Type: application/json` mit.
Spezifikation	OpenAPI-3.1-Dokument

Ersetzen Sie <ihre-url> durch die Adresse, unter der Sie sich bei plnnrly anmelden, zum Beispiel acme.plnnrly.com. Nutzt Ihre Organisation eine eigene Domain, verwenden Sie diese Domain: Die API antwortet nur unter genau dieser Adresse und leitet nie weiter. Ein gemeinsames api.plnnrly.com gibt es nicht.

In plnnrly öffnet API-Zugang im Benutzermenü die Seite API-Tokens. Dort steht Ihre Basis-URL zum Kopieren bereit.

Zwei Wege zur Authentifizierung

Sie bauen	Verwenden Sie
Skripte und Integrationen für sich selbst oder Ihre Organisation	Ein persönliches Zugriffstoken, das Sie in plnnrly erstellen. Siehe API-Tokens (Englisch).
Eine App, die andere Personen installieren und bei der sie sich anmelden	Anmeldung per OAuth: Authorization-Code-Flow mit PKCE, wobei sich die App selbst registriert. Für Desktop- und Kommandozeilen-Apps; wer sich anmeldet, braucht das Recht API-Tokens verwalten. Siehe Anmeldung per OAuth (Englisch).

In beiden Fällen handelt jede Anfrage im Namen einer Person, mit deren Rechten und nicht mehr. Apps mit einer Anmeldung per OAuth können über die REST-API nicht löschen.

Ein Token erstellen

Öffnen Sie in plnnrly API-Zugang im Benutzermenü (oben rechts, unter Ihrem Namen) und wählen Sie Token erstellen.
Tragen Sie unter Name einen Namen für das Token ein.
Wählen Sie unter Berechtigungen die Option Lesen, Schreiben oder Löschen; die Liste bietet nur an, was Ihre Rechte erlauben. Schreiben umfasst Lesen, und Löschen umfasst Schreiben und Lesen. Das Token speichert sie als api:read, api:write und api:destroy, oder pro Ressource, etwa api:read:projects, wenn Sie Bereiche ausfüllen.
Lassen Sie Bereiche leer, um die Berechtigungen für alle Ressourcen zu erteilen, oder wählen Sie die Teile von plnnrly, auf die das Token beschränkt sein soll. Die Liste bietet nur Teile an, für die Sie Rechte haben.
Legen Sie Läuft ab am fest. Das Feld ist ein Pflichtfeld, ist mit dem Datum in 90 Tagen vorbelegt und darf höchstens 12 Monate in der Zukunft liegen.
Kopieren Sie das Token. Es wird nur einmal angezeigt.

API-Zugang erscheint im Benutzermenü nur, solange die REST-API eingeschaltet ist und Sie das Recht API-Tokens verwalten haben. Siehe wer Tokens erstellen darf. Sie können zehn aktive Tokens gleichzeitig haben.

Das Feld Berechtigungen ist die Token-Berechtigung: Es legt fest, was das Token tun darf. Das ist nicht dasselbe wie die Rechte, die Ihnen Ihre Rolle gibt. Beides gilt, deshalb kann ein Token nie mehr, als Sie in plnnrly können. API-Tokens (Englisch) beschreibt das Erneuern, das Widerrufen und das ganze Formular.

Jede Operation nennt, was sie braucht

Jede Operationsseite in der Referenz (Englisch) nennt die Token-Berechtigung und das plnnrly-Recht, die die Operation braucht, und wie viel sie von Ihrem Rate-Limit verbraucht. Berechtigung und Recht werden bei jeder Anfrage geprüft, und der Typ eines 403 sagt Ihnen, woran die Anfrage gescheitert ist:

insufficient-token-scope: Die Token-Berechtigung deckt die Operation nicht ab. Verwenden Sie ein Token mit einer weiter gefassten Berechtigung.
insufficient-permission: Ihrer Rolle fehlt das Recht. Bitten Sie einen Administrator, Ihre Rolle zu ändern.
forbidden-by-policy: Mit diesem bestimmten Datensatz dürfen Sie das nicht tun.

Sehen, was Ihre Organisation anbietet

Die Discovery-Anfrage (Englisch) listet auf, was Ihre Organisation anbietet: jede Ressource mit ihren URLs und Operationen. Jedes persönliche API-Token kann sie aufrufen; ein Recht braucht sie nicht.

Terminal

curl https://<ihre-url>/api/v2/ \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Der Header Accept ist optional: Lassen Sie ihn weg, oder senden Sie application/json.

Die Discovery-Anfrage lässt Bereiche weg, die Ihre Organisation nicht nutzt, etwa die Abrechnung. Sie prüft nicht, welche Ressourcen Ihre Token-Berechtigung oder Ihre Rolle abdecken. Eine aufgeführte Ressource kann also trotzdem mit 403 antworten.

Wenn die API ausgeschaltet ist

Ein Administrator kann die REST-API unter Einstellungen › Verwaltung › MCP & API ausschalten. Solange sie aus ist, antwortet jede Anfrage mit 404 endpoint-not-found, auch eine Anfrage mit einem Token, das vorher funktioniert hat. Siehe was passiert, wenn ein Schalter aus ist.

Wie es weitergeht

Einstieg (Englisch): vom Token bis zum ersten Schreibzugriff.
Referenzübersicht (Englisch): wie die Referenz aufgebaut ist, und alle Anleitungen.
Fehler und Wiederholungen (Englisch): jeder Problemtyp und was dagegen hilft.
/openapi.json: die vollständige Spezifikation, für Code-Generatoren und Tools.

Für KI-Assistenten

Soll ein KI-Assistent mit Ihren plnnrly-Daten arbeiten, nutzen Sie den MCP-Server. Er erreicht dieselben Operationen wie Sie, außer Datei-Uploads, und Sie müssen keinen Client schreiben.