# REST-API-Übersicht Was die REST-API von plnnrly ist, wo sie erreichbar ist, wie Sie sich authentifizieren und wie Sie ein Token bekommen. 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:///api/v2` | | **Authentifizierung** | `Authorization: Bearer ` | | **Format** | JSON. Senden Sie bei jeder Anfrage mit Body `Content-Type: application/json` mit. | | **Spezifikation** | [OpenAPI-3.1-Dokument](https://developers.plnnrly.com/openapi.json) | Ersetzen Sie `` 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)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/). | | 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)](https://developers.plnnrly.com/en/docs/api/v2/guides/oauth-apps/). | 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 1. Öffnen Sie in plnnrly **API-Zugang** im Benutzermenü (oben rechts, unter Ihrem Namen) und wählen Sie **Token erstellen**. 2. Tragen Sie unter **Name** einen Namen für das Token ein. 3. 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. 4. 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. 5. 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. 6. 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](https://developers.plnnrly.com/de/docs/administration/#permissions). 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)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/) beschreibt das Erneuern, das Widerrufen und das ganze Formular. ## Jede Operation nennt, was sie braucht Jede Operationsseite in der [Referenz (Englisch)](https://developers.plnnrly.com/en/docs/api/v2/) 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](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-token-scope): Die Token-Berechtigung deckt die Operation nicht ab. Verwenden Sie ein Token mit einer weiter gefassten Berechtigung. - [insufficient-permission](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-permission): Ihrer Rolle fehlt das Recht. Bitten Sie einen Administrator, Ihre Rolle zu ändern. - [forbidden-by-policy](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#forbidden-by-policy): Mit diesem bestimmten Datensatz dürfen Sie das nicht tun. ## Sehen, was Ihre Organisation anbietet Die [Discovery-Anfrage (Englisch)](https://developers.plnnrly.com/en/docs/api/v2/discovery/) 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. ```bash curl https:///api/v2/ \ -H "Authorization: Bearer " \ -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](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#endpoint-not-found), auch eine Anfrage mit einem Token, das vorher funktioniert hat. Siehe [was passiert, wenn ein Schalter aus ist](https://developers.plnnrly.com/de/docs/administration/#when-switched-off). ## Wie es weitergeht - [Einstieg (Englisch)](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/): vom Token bis zum ersten Schreibzugriff. - [Referenzübersicht (Englisch)](https://developers.plnnrly.com/en/docs/api/v2/): wie die Referenz aufgebaut ist, und alle Anleitungen. - [Fehler und Wiederholungen (Englisch)](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/): jeder Problemtyp und was dagegen hilft. - [/openapi.json](https://developers.plnnrly.com/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](https://developers.plnnrly.com/de/docs/mcp/). Er erreicht dieselben Operationen wie Sie, außer Datei-Uploads, und Sie müssen keinen Client schreiben.