Naar de inhoud
kodari

API voor ontwikkelaars

Met de Kodari API haal je dezelfde gegevens op als op onze site: shops, gecontroleerde codes met hun voorwaarden, het kortingsritme van een shop, lopende acties en de goedkoopste route voor een bestelling. Handig voor een eigen app of voor een AI agent die namens iemand zoekt. De API is versie 1 en alleen om te lezen.

Neutraal, net als de site

De volgorde van codes en routes hangt af van wat je bespaart, nooit van wat wij aan een shop verdienen. In de API staat geen commissie, geen programma en geen netwerk.

Toegang en sleutels

Zonder sleutel kun je de API proberen, met hooguit 60 aanroepen per minuut per IP-adres. Met een sleutel krijg je eigen limieten, zie je in de headers wat er over is, en staat bij een code de code zelf erin.

Stuur de sleutel mee als header, nooit in de URL: die belandt in logs. 

Authorization: Bearer kdr_...
X-Api-Key: kdr_...

Een sleutel vraag je aan via het contactformulier. Noem je naam, waar je de API voor gebruikt en welke rechten je nodig hebt.

Rechten per sleutel

  • merchants:read: Shops zoeken en bekijken.
  • coupons:read: Codes met verificatie lezen.
  • routes:read: Bespaarroutes berekenen.
  • pools:read: Open Samen Kopen-pools lezen.
  • code_requests:write: Codes aanvragen bij een shop, alleen op verzoek.

Limieten

Een sleutel mag standaard 60 aanroepen per minuut en 10.000 per dag doen. Elk antwoord bevat X-RateLimit-Limit en X-RateLimit-Remaining. Kom je erboven, dan krijg je status 429 met Retry-After: het aantal seconden tot je weer mag.

Endpoints

Alle antwoorden zijn JSON. Tijden zijn ISO 8601 met tijdzone, bedragen in euro.

GET /api/v1/merchants

Shops zoeken op naam of domein. Zonder zoekterm de shops met de hoogste score, per pagina.

  • q: Zoekterm, optioneel.
  • page: Paginanummer, optioneel.

Recht: merchants:read

GET /api/v1/merchants/{slug}

Eén shop met profiel, actieve codes en deals, en het kortingsritme onder `rhythm` (of null bij te weinig historie).

Recht: merchants:read

GET /api/v1/merchants/{slug}/coupons

Actieve codes en deals van één shop, in de volgorde van de shoppagina.

Recht: coupons:read

GET /api/v1/coupons

Codes zoeken, of de nieuwste publieke codes, per pagina.

  • q: Zoekterm, optioneel.
  • exclusive: Met 1 alleen codes die je alleen via ons krijgt.
  • page: Paginanummer, optioneel.

Recht: coupons:read

GET /api/v1/coupons/{id}

Eén code met de nieuwste controles onder `verification_history`. Met een sleutel staat de code zelf erin, behalve bij codes die we alleen per mail geven.

Recht: coupons:read

GET /api/v1/events

Lopende en komende acties, zoals Black Friday, de eerstvolgende eerst.

Recht: coupons:read

GET /api/v1/pools

Open Samen Kopen-groepen, alleen geteld en nooit per deelnemer.

  • merchant: Slug van een shop, optioneel.

Recht: pools:read

POST /api/v1/routes

De goedkoopste routes voor een shop en een orderbedrag: welke codes en voordelen samen gaan, en wat je dan betaalt.

  • merchant: Slug van de shop, verplicht.
  • order_amount: Orderbedrag in euro met een punt als decimaalteken, verplicht.
  • context: Optioneel: new_customer, prepurchase_ok, is_student, memberships, payment_methods.

Recht: routes:read

POST /api/v1/code-requests

Een code aanvragen bij een shop. Alleen met de scope `code_requests:write`, die je op verzoek krijgt.

  • merchant_domain: Domein van de webshop, verplicht.
  • email: E-mailadres van wie de code wil, optioneel.

Recht: code_requests:write

GET /api/v1/code-requests/{id}

Stand en tijdlijn van één aanvraag, zonder adressen en zonder de code.

Recht: code_requests:write

MCP-server voor AI agents

Werk je met een AI-assistent die MCP kent, zoals Claude of ChatGPT, dan kun je dezelfde gegevens als tools aanbieden. De server spreekt Streamable HTTP op dit adres: 

https://kodari.nl/mcp

Geef je sleutel mee in dezelfde header als bij de API. Elke tool is een aanroep van de API: dezelfde rechten, dezelfde limieten en dezelfde links, en hij telt mee in je gebruik. Zonder sleutel werkt het ook, met de limiet per IP-adres. Net als in de lijsten van de API staat de code zelf niet in een tool. Stuur mensen via de meegegeven link naar de shop.

search_merchants

Zoekt een Nederlandse webshop op naam of domein. Geeft per shop de slug, naam, domein, categorie en de pagina op Kodari. Gebruik de slug in de andere tools.

get_coupons

Geeft de actieve kortingscodes en deals van een shop, door Kodari gecontroleerd. Elke code heeft bewijs: verification.verified_at (laatste controle), verification.success_rate_7d, confidence en source. Noem de controledatum als je een code laat zien, en stuur mensen naar de shop via de meegegeven link, niet via een eigen link.

get_discount_rhythm

Is deze korting goed voor deze shop? Geeft het kortingsritme uit de historie van Kodari: de gebruikelijke korting (typical_low tot typical_high), de beste korting ooit, en per maand hoe vaak er een code was. Vergelijk een code hiermee, of met het rhythm_label bij get_coupons. Is rhythm null, dan is er te weinig historie; zeg dat eerlijk.

best_savings_route

Rekent voor een shop en een orderbedrag de goedkoopste route uit: welke code, cashback of cadeaukaart samen werken, wat je dan betaalt, met aannames en zekerheid per route. De bedragen komen uit de rekenmodule van Kodari; neem ze over zoals ze zijn. Stuur de gebruiker naar de shop via de meegegeven link. Gebruik alleen een orderbedrag dat de gebruiker zelf noemde.

upcoming_sales

Geeft de lopende en komende kortingsacties in Nederland, zoals Black Friday, de eerstvolgende eerst. is_running zegt of een actie nu loopt. Handig om te zeggen of wachten op een actie zin heeft.

Bewijs bij elke code

Elke code draagt mee waarom we hem tonen:

  • verification.status: waar de code staat, bijvoorbeeld verified of published.
  • verification.verified_at: wanneer we de code voor het laatst controleerden.
  • verification.success_rate_7d: het deel van de stemmen van de laatste 7 dagen dat zei dat de code werkte. Met minder dan 5 stemmen is dit null: een paar stemmen zeggen te weinig.
  • confidence: hoe zeker we de voorwaarden hebben gelezen, van 0 tot 1.
  • source: waar de code vandaan komt, zoals een feed van een netwerk, de shop zelf of een bezoeker.
  • rhythm_label: hoe de korting zich verhoudt tot wat we bij die shop meestal zien (best_ever, above_usual, usual of below_usual), of null bij te weinig historie. Zie hoe wij meten.

GET /api/v1/coupons/{id} geeft daarnaast de nieuwste 20 controles: hoe (rules, landing of user_votes), met welke uitkomst en wanneer. Noem de controledatum als je een code aan iemand laat zien.

Voorbeeld van GET /api/v1/coupons/{id} met een sleutel. De waarden zijn verzonnen:

{
    "data": {
        "id": 123,
        "merchant_id": 45,
        "type": "code",
        "title": "15% op alles",
        "conditions": [
            "Vanaf € 50,00 besteding."
        ],
        "discount": {
            "type": "percent",
            "value": 15,
            "max_amount": 25,
            "min_order_value": 50
        },
        "is_exclusive": true,
        "requires_code": true,
        "code": "VOORBEELD15",
        "expires_at": "2026-11-30T22:59:59+00:00",
        "verification": {
            "status": "verified",
            "verified_at": "2026-09-24T08:10:00+00:00",
            "success_rate_7d": 0.86,
            "votes_7d": 42
        },
        "confidence": 0.9,
        "source": "network",
        "rhythm_label": "above_usual",
        "link": "https://kodari.nl/uit/voorbeeldshop?code=123&van=api&c=7"
    },
    "verification_history": [
        {
            "method": "landing",
            "result": "passed",
            "checked_at": "2026-09-24T08:10:00+00:00"
        },
        {
            "method": "user_votes",
            "result": "passed",
            "checked_at": "2026-09-23T19:02:00+00:00"
        }
    ]
}

Foutcodes

  • 401: de sleutel is onbekend of ingetrokken.
  • 403: de sleutel heeft geen recht op dit endpoint.
  • 404: de shop, code of aanvraag bestaat niet, of is niet publiek.
  • 422: de invoer klopt niet. Onder errors staat per veld wat er mis is.
  • 429: te veel aanroepen. Wacht het aantal seconden uit Retry-After.

Wat we van je vragen

  • Stuur mensen naar een shop via de link uit de API.
  • Publiceer onze database niet in bulk opnieuw. Codes tonen aan iemand die zoekt mag, een kopie van alle codes neerzetten niet.
  • Een code die alleen per mail gaat, staat nooit in de API. Probeer hem niet op een andere manier op te halen.