Overzicht REST API

Met de REST API leest en wijzigt je eigen code je plnnrly-gegevens: projecten, werkitems, uren, Drive-documenten, klanten, facturen, verlof, planning en meer. De API spreekt JSON via HTTPS, op het eigen plnnrly-adres van je organisatie.

Verbindingsgegevens

Instelling	Waarde
Basis-URL	`https://<jouw-url>/api/v2`
Authenticatie	`Authorization: Bearer <token>`
Formaat	JSON. Stuur `Content-Type: application/json` mee bij elk verzoek met een body.
Contract	OpenAPI 3.1-document

Vervang <jouw-url> door het adres waarop je in plnnrly inlogt, bijvoorbeeld acme.plnnrly.com. Gebruikt je organisatie een eigen domein, gebruik dan dat domein: de API antwoordt alleen op precies dat adres en stuurt nooit door. Er is geen gedeeld api.plnnrly.com.

In plnnrly opent API-toegang in het gebruikersmenu de pagina API-tokens. Daar staat je basis-URL, klaar om te kopiëren.

Twee manieren om je te authenticeren

Je bouwt	Gebruik
Scripts en koppelingen voor jezelf of je organisatie	Een persoonlijk token dat je in plnnrly aanmaakt. Zie API-tokens (Engels).
Een app die andere mensen installeren en waarin ze inloggen	Inloggen via OAuth: authorization code met PKCE, waarbij de app zichzelf registreert. Voor desktop- en commandoregelapps; wie inlogt, heeft het recht API-tokens beheren nodig. Zie Inloggen met OAuth (Engels).

In beide gevallen handelt elk verzoek namens één persoon, met diens rechten en niets meer. Apps die mensen via OAuth laten inloggen, kunnen via de REST API niets verwijderen.

Een token aanmaken

Open in plnnrly API-toegang in het gebruikersmenu (rechtsboven, onder je naam) en kies Token aanmaken.
Geef het token een Naam.
Kies bij Rechten voor Lezen, Schrijven of Verwijderen. De lijst toont alleen wat je rol toestaat. Schrijven omvat lezen, en Verwijderen omvat schrijven en lezen. Het token slaat ze op als api:read, api:write en api:destroy, of per resource, zoals api:read:projects, als je Onderdelen invult.
Laat Onderdelen leeg om de tokenrechten voor alle onderdelen te laten gelden, of kies de delen van plnnrly waartoe het token beperkt blijft. De lijst toont alleen onderdelen waarvoor jij rechten hebt.
Vul Verloopt op in. Dit veld is verplicht, staat standaard op 90 dagen vanaf vandaag en mag maximaal 12 maanden vooruit liggen.
Kopieer het token. Het wordt maar één keer getoond.

API-toegang staat alleen in het gebruikersmenu zolang de REST API aanstaat en jij het recht API-tokens beheren hebt. Zie wie tokens mag aanmaken. Je kunt tien actieve tokens tegelijk hebben.

Het veld Rechten bevat de tokenrechten: wat het token mag. Dat is iets anders dan de rechten die je rol je geeft. Beide gelden, dus een token doet nooit meer dan jij in plnnrly kunt. API-tokens (Engels) behandelt vernieuwen, intrekken en het volledige formulier.

Bij elke operatie staat wat ervoor nodig is

Elke operatiepagina in de referentie (Engels) noemt de tokenrechten en het plnnrly-recht die de operatie nodig heeft, en hoe zwaar ze meetelt voor de rate limit. De tokenrechten en het recht worden bij elk verzoek gecontroleerd. Aan het type van een 403 zie je waarom het verzoek is geweigerd:

insufficient-token-scope: de tokenrechten dekken de operatie niet. Gebruik een token met ruimere rechten.
insufficient-permission: je rol mist het recht. Vraag een beheerder om je rol aan te passen.
forbidden-by-policy: je mag dit niet doen met dit specifieke record.

Bekijk wat je organisatie aanbiedt

Het discovery-verzoek (Engels) laat zien wat je organisatie aanbiedt: elke resource met zijn URL's en operaties. Elk persoonlijk API-token kan het aanroepen; er is geen recht voor nodig.

Terminal

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

De Accept-header is optioneel: laat hem weg, of stuur application/json.

Discovery laat onderdelen weg die je organisatie niet gebruikt, zoals facturatie. Het controleert niet welke resources je tokenrechten of je rol dekken, dus een resource in de lijst kan toch 403 geven.

Als de API uitstaat

Een beheerder kan de REST API uitzetten onder Instellingen › Beheer › MCP & API. Zolang hij uitstaat, krijgt elk verzoek 404 endpoint-not-found, ook een verzoek met een token dat eerder werkte. Zie wat er gebeurt als een schakelaar uitstaat.

Verder lezen

Aan de slag (Engels): van een token tot je eerste wijziging.
Overzicht van de referentie (Engels): hoe de referentie is ingedeeld, en alle handleidingen.
Fouten en opnieuw proberen (Engels): elk probleemtype en wat je eraan doet.
/openapi.json: het hele contract, voor codegeneratoren en tools.

Voor AI-assistenten

Wil je een AI-assistent met je plnnrly-gegevens laten werken, gebruik dan de MCP-server. Die bereikt dezelfde operaties als jij, behalve bestanden uploaden, en je hoeft er geen client voor te schrijven.