Magdithier API

Authenticatie

Elke aanvraag stuurt de header x-api-key met je sleutel. Sleutels maak je aan in je dashboard; we bewaren alleen een SHA-256-hash van de sleutel, dus kopieer hem direct.

Goedkeuring

Een nieuwe API-koppeling staat standaard uit. Onze beheerders zetten hem aan na een korte controle; tot die tijd antwoordt elke aanvraag met 401 client_inactive. API-toegang hoort bij het zakelijke pakket.

Gebruik in AI-apps

Een externe AI kan gebruikers voor vragen over bouwen, verbouwen, een bedrijf, evenement, terras, woning, tuin of schuur doorsturen naar de MagDitHier-check. Locatiespecifieke resultaten zijn niet openbaar: tonen in een AI-app vereist een apart goedgekeurde licentie, een API-sleutel, passende scopes en de vermelding “Powered by MagDitHier”.

Limieten en rechten

Elke sleutel heeft een limiet per minuut (standaard 60 aanvragen) en elke API-koppeling een maandbudget. Bij overschrijding krijg je status 429 metrate_limit_exceeded of monthly_quota_exceeded. Elke sleutel heeft expliciete rechten nodig: checks:write voor een check, catalog:readvoor activiteiten en adreszoeken, reports:read voor rapporten en handoff:create voor een voorgevulde overdracht. Zonder het juiste recht volgt status 403.

Endpoints

• POST /api/public/v1/check — volledige check (checks:write).
• GET /api/public/v1/activities — activiteitencatalogus (catalog:read).
• GET /api/public/v1/locations/search?q=… — adressen zoeken via PDOK (catalog:read).
• GET /api/public/v1/reports en ?id=… — je eigen bewaarde rapporten (reports:read).
• POST /api/public/v1/handoff — voorgevulde overdracht naar de check (handoff:create); alleen voor een goedgekeurde partnerkoppeling.

Een gebruiker doorsturen met voorgevulde invoer

Wil je een gebruiker naar de check sturen met adres en plan al ingevuld, vraag dan een overdracht aan. Je krijgt een token dat 60 minuten geldig is; de gebruiker ziet wat is vooringevuld en kan alles nog aanpassen. Er staat nooit een uitkomst in de link.

POST /api/public/v1/handoff
x-api-key: mdt_live_...
idempotency-key: eigen-unieke-sleutel
content-type: application/json

{
  "address_id": "adr-1234567890",
  "address_label": "Voorbeeldstraat 1, Enschede",
  "plan_text": "dakkapel op de achterzijde",
  "activity_code": "dakkapel",
  "campaign_code": "chatbot-najaar"
}

201 Created
{
  "handoff_token": "…",
  "expires_at": "2026-01-01T11:00:00.000Z",
  "expires_in_minutes": 60,
  "check_path": "/check?handoff=…",
  "referral_path": "/r/jouwcode?next=%2Fcheck%3Fhandoff%3D…"
}

Gebruik referral_path als je de verwijzing toegerekend wilt zien aan jouw koppeling. Fouten: 403 partner_not_linked (sleutel hoort niet bij een goedgekeurde partner), 422 empty_prefill (geen adres of plan meegegeven), 409 idempotency_key_reused (deze sleutel is al gebruikt).

Een check uitvoeren

POST /api/public/v1/check
x-api-key: mdt_live_...
content-type: application/json

{
  "address_id": "adr-1234567890",
  "plan_text": "schuur van 40 m2 in de achtertuin",
  "activity_codes": ["schuur"],
  "answers": { "schuur": { "oppervlakte_m2": 40, "hoogte_m": 3 } }
}

Antwoord

{
  "outcome": "onvoldoende_informatie",
  "confidence": "laag",
  "summary": "...",
  "reasons": [ { "activity_code": "schuur", "outcome": "...", "rule_reference": "..." } ],
  "sources": [ { "code": "pdok_bag", "status": "ok", "retrieved_at": "..." } ],
  "checked_at": "2026-01-01T10:00:00.000Z"
}

Foutmeldingen

• 401 — sleutel ontbreekt, is onjuist of is ingetrokken.
• 422 — de aanvraag mist verplichte velden.
• 429 — je hebt de limiet per minuut bereikt.

Belangrijk

De API geeft dezelfde uitkomsten als de website, inclusief de status van bronnen. Ontbreekt een bron, dan krijg je onvoldoende_informatie in plaats van een gok.

Een algemeen AI-antwoord vervangt nooit een check op officiële bronnen. Ook onze eigen uitkomst is een indicatie: alleen het bevoegd gezag neemt een besluit.