Curbed API
Je eigen gegevens uitlezen vanaf je eigen systemen.
Laatst bijgewerkt op 24 september 2026
Curbed heeft een API waarmee je bedrijf de eigen gegevens kan uitlezen: de meldingen, de cijfers, en het wagenpark en het personeel als bestand. Bedoeld om Curbed de bron te laten zijn voor het systeem dat je al hebt — een intranet, een leaseadministratie, een dashboard — in plaats van een tweede systeem ernaast.
Deze pagina is de hele documentatie. Ze beschrijft wat er vandaag is, niet wat er ooit komt.
Versie 1 leest alleen
Met een sleutel kun je niets aanmaken, wijzigen of verwijderen. Er zijn in v1 geen POST-, PATCH-, PUT- of DELETE-adressen voor sleutels, en een sleutel die ze zou kunnen uitvoeren kan niet worden aangemaakt.
De reden staat in één zin: een wijziging die met een sleutel is gemaakt heeft geen eerlijke auteur. Curbed legt bij elke melding, statuswijziging en notitie vast wie het deed, en in een dossier waar een chauffeur jaren later op wordt aangesproken hoort geen verzonnen naam.
Schrijven komt terug zodra daar een eerlijk antwoord op is. Tot die tijd zeggen we het liever hier dan nadat je een middag hebt gebouwd.
Inloggen met een sleutel
Een beheerder maakt een API-sleutel aan in Curbed zelf, bij Instellingen. De sleutel wordt één keer getoond en daarna nooit meer; bewaar hem zoals je een wachtwoord bewaart, en niet in een repository.
Stuur hem bij elk verzoek mee in de Authorization-header:
Authorization: Bearer curbed_sk_7f3a9c2e…Een sleutel hoort bij je bedrijf, niet bij een persoon. Hij kan dus geen gegevens van een ander bedrijf lezen, en hij blijft werken als degene die hem aanmaakte weggaat. Welke rechten hij heeft, kiest de beheerder bij het aanmaken.
Raakt een sleutel kwijt of komt hij op straat te liggen, trek hem dan in en maak een nieuwe aan. Intrekken werkt direct. Een ingetrokken sleutel wordt niet gewist: dat een sleutel gegevens heeft opgehaald is een feit dat in het dossier blijft staan.
Adres en versie
Alles staat onder één adres, en het versienummer hoort bij het adres:
https://api.curbed.cab/v1Antwoorden zijn JSON, behalve de exports — die zijn CSV. Tijdstippen zijn ISO 8601 in UTC, tenzij een endpoint iets anders zegt; de exports schrijven op de klok van je eigen bedrijf.
Je hoeft nergens te vermelden bij welk bedrijf je hoort. De sleutel zegt dat al, en een tweede plek waar het bedrijf genoemd kan worden is een tweede plek waar het fout kan staan.
Wat je kunt lezen
Alle adressen hieronder staan onder de basis-URL en zijn GET. De kolom Rechten noemt het recht dat de sleutel moet dragen — precies zoals het in het aanmaakscherm heet, zodat je je beheerder er letterlijk om kunt vragen.
Een sleutel leest je hele bedrijf, over alle vestigingen heen. Een adres dat hier niet staat, bestaat voor een sleutel niet.
Meldingen
| Endpoint | Rechten |
|---|---|
GET /reportsHet meldingenoverzicht, met dezelfde filters, sortering en zoekopdracht als het scherm. | view_all_reports |
GET /reports/{id}Eén melding, met voertuig, categorie, foto’s, melder en behandelaar. | view_all_reports |
GET /reports/{id}/eventsDe tijdlijn van een melding als losse gebeurtenissen, zodat je de zin in je eigen taal opbouwt. | view_all_reports |
GET /reports/status-countsHoeveel meldingen er openstaan, in behandeling zijn en zijn afgehandeld. | view_all_reports |
GET /statsAlle cijfers van het statistiekenscherm, voor één periode. | view_all_reports |
Exports (CSV)
| Endpoint | Rechten |
|---|---|
GET /export/damagesDe meldingen als CSV, met dezelfde filters als het overzicht. | export_import |
GET /export/carsHet wagenpark als CSV. | export_import |
GET /export/statsDe cijfers als CSV, in lange vorm: sectie, label, waarde. | export_import |
GET /export/usersHet personeelsbestand als CSV: e-mailadres, naam en rol. | export_import |
Als er iets misgaat
Een fout komt terug als application/problem+json (RFC 9457) met een vaste, machineleesbare code:
{
"type": "https://curbed.cab/problems/forbidden",
"status": 403,
"code": "forbidden"
}| Code | Status | Betekenis |
|---|---|---|
unauthenticated | 401 | Er is geen sleutel meegestuurd, of de header heeft niet de vorm die hierboven staat. |
invalid_token | 401 | De sleutel bestaat niet, is ingetrokken, of is onderweg verminkt geraakt. |
forbidden | 403 | De sleutel bestaat, maar draagt dit recht niet. Laat je beheerder een nieuwe sleutel aanmaken met het recht erbij. |
key_not_permitted | 403 | Dit adres is niet met een API-sleutel te benaderen. De API is alleen-lezen: schrijfacties en alles wat buiten de tabel hierboven valt, kunnen alleen door een ingelogde medewerker. |
invalid_id | 400 | Een id in het pad is geen geldige uuid. |
damage_not_found | 404 | Geen melding met dit id binnen je bedrijf. |
not_found | 404 | Dit adres bestaat niet. Leg het naast de tabel hierboven. |
rate_limited | 429 | De limiet voor dit uur is bereikt. Retry-After zegt hoeveel seconden je moet wachten. |
internal_error | 500 | Er ging iets mis aan onze kant. Het verzoek is niet uitgevoerd; probeer het opnieuw, en laat het ons weten als het blijft gebeuren. |
Kijk naar code, nooit naar de statuscode. De status is er voor proxies en logboeken; de code is de afspraak. Er staat met opzet geen uitleg in mensentaal in het antwoord — die zou Engels zijn, en jouw chauffeurs lezen Nederlands.
Een rij die niet bestaat en een rij die van een ander bedrijf is, geven hetzelfde antwoord. Dat is geen slordigheid: anders zou het antwoord bevestigen dat de gegevens van dat andere bedrijf bestaan.
Hoe vaak je mag vragen
Elke sleutel mag 600 verzoeken per uur doen. Ruim voor een intranetpagina die bij het laden een lijst ophaalt, krap voor een script dat in een lus staat.
Ga je eroverheen, dan antwoordt de API met 429 en een Retry-After-header met het aantal seconden tot je weer verder kunt. Wacht die af — blijven kloppen verkort hem niet.
Heb je structureel meer nodig, bijvoorbeeld voor een nachtelijke export van het hele wagenpark, vraag het dan. De limiet staat per sleutel en kan omhoog.
Voorbeelden
Met echte wagennummers en Nederlandse categorieën, zodat je ziet wat je terugkrijgt. Vervang de sleutel door je eigen.
Het hele wagenpark als CSV — wat je nodig hebt als je intranet wagens bij nummer kent.
Verzoek
curl -s https://api.curbed.cab/v1/export/cars \
-H "Authorization: Bearer curbed_sk_7f3a9c2e…" \
-o wagenpark.csvAntwoord
number,type,plate,active,location
2098,Mercedes Vito,92-NXR-3,true,Hoofdvestiging
2174,Mercedes Vito,64-KTB-8,true,HoofdvestigingDe openstaande meldingen, hoogste prioriteit eerst.
Verzoek
curl -s "https://api.curbed.cab/v1/reports?status=open&sort=priority&dir=desc" \
-H "Authorization: Bearer curbed_sk_7f3a9c2e…"Antwoord
{
"reports": [
{
"id": "c41b8e02-7d6a-4f15-b3c9-08e2a5d74169",
"status": "reported",
"priority": "high",
"side": "left",
"description": "Linker schuifdeur klemt — rubber versleten",
"descriptionTranslated": null,
"categoryId": "5e8a1c34-9b07-4d62-8f1a-c3d05b726e48",
"category": { "id": "5e8a1c34-9b07-4d62-8f1a-c3d05b726e48", "name": "Carrosserie" },
"reportedAt": "2026-09-14T06:52:11.004Z",
"repairCostCents": null,
"noteCount": 2,
"car": { "id": "0f1e6a54-2c7b-4a19-9d03-6b1f7c8e4d22", "number": "2098", "plate": "92-NXR-3" },
"photos": []
}
],
"nextCursor": null,
"appliedStatus": "open",
"appliedLocation": null,
"timeZone": "Europe/Amsterdam"
}Alle meldingen van dit jaar als CSV, voor je eigen rapportage.
Verzoek
curl -s "https://api.curbed.cab/v1/export/damages?status=all&from=2026-01-01" \
-H "Authorization: Bearer curbed_sk_7f3a9c2e…" \
-o schades.csvAntwoord
id,car_number,car_plate,car_type,description,category,side,priority,status,…
c41b8e02-7d6a-4f15-b3c9-08e2a5d74169,2098,92-NXR-3,Mercedes Vito,Linker schuifdeur klemt — rubber versleten,Carrosserie,left,high,reported,…
9d720f5b-3e18-4c07-a6d2-5b91f0c4e873,2174,64-KTB-8,Mercedes Vito,Ster in de voorruit bestuurderszijde,Ruitschade,front,medium,completed,…En zo ziet het eruit als je te snel gaat.
Verzoek
curl -si "https://api.curbed.cab/v1/reports" \
-H "Authorization: Bearer curbed_sk_7f3a9c2e…"Antwoord
HTTP/1.1 429 Too Many Requests
Retry-After: 1800
Content-Type: application/problem+json
{"type":"https://curbed.cab/problems/rate_limited","status":429,"code":"rate_limited"}Wat wij beloven
Een API aanbieden is een belofte, geen functie. Dit is de belofte, en ze geldt voor iedereen die een sleutel heeft:
- v1 breekt niet. Er kunnen velden en endpoints bij komen, maar een bestaand veld verandert niet van betekenis, verandert niet van type, en verdwijnt niet.
- Moet er ooit toch iets breken, dan heet dat v2 en krijgt het een eigen adres. v1 blijft er 12 maanden naast staan en blijft in die periode gewoon antwoorden.
- Zo’n wijziging kondigen wij per e-mail aan bij elk bedrijf met een actieve sleutel. Niet in een changelog die niemand leest.
Wat wij daarvoor terugvragen is één ding: laat je koppeling velden die ze niet kent overslaan in plaats van erop stuklopen. Dan is een toevoeging aan onze kant geen werk aan die van jou.
Concreet betekent dit dat een koppeling die je dit jaar bouwt, volgend jaar nog werkt, en dat je het minstens 12 maanden van tevoren weet als dat een keer niet zo is. Dat is wat je kunt begroten.
Vragen
Iets dat niet klopt op deze pagina, een hogere limiet, of een endpoint dat je mist en wij nog niet hebben — mail ons. Wij zijn ook degenen die je mailen als er ooit iets aan v1 verandert.