De API

Zes leesroutes op je eigen cijfers. Ze geven precies wat je in je dashboard ziet, in JSON. Er is geen schrijfroute: metingen starten kost geld en dat hoort niet achter een sleutel te zitten die in een script staat.

Introductie

Groei en Bureau. Je maakt een sleutel in je dashboard, bij Beheer, onder API. De sleutel staat één keer op het scherm. Wij bewaren alleen een versleutelde afdruk, dus wij kunnen hem later ook niet meer tonen.

Elke route hangt onder één basisadres. Alles loopt over HTTPS en elke route is een GET.

Basisadresurl

https://www.vermeld.be/api/v1

Snel aan de slag

1Maak een sleutel in je dashboard, onder API. Kopieer hem meteen: hij staat er maar één keer.
2Doe je eerste verzoek. Vervang vm_live_... door je eigen sleutel.
3Je krijgt je websites terug. De id uit die lijst gaat in elke andere route.

Maak een sleutel

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": [
    {
      "id": "6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18",
      "domein": "bakkerijjan.be",
      "merknaam": "Bakkerij Jan",
      "aangemaakt_op": "2026-03-04T09:11:22.000Z"
    }
  ],
  "gemeten_op": null
}

Authenticatie

Stuur je sleutel mee als kopregel. Nooit in de webadresregel: die komt in serverlogs terecht.

Een sleutel begint met vm_live_ en telt daarna 32 tekens. Een sleutel in een andere vorm krijgt meteen geen_sleutel terug.

Kopregelhttp

Authorization: Bearer vm_live_...

Antwoordvorm

Eén vorm bij goed en één bij fout. Zo hoeft je code niet per route te raden waar het antwoord staat.

gemeten_op is null zolang er niets gemeten is. Dat geldt overal: null betekent niet gemeten, nul betekent gemeten en afwezig. Wie die twee door elkaar haalt, ziet een score kelderen door een storing bij ons.

De uitleg volgt je Accept-Language: Nederlands of Frans. De code in fout verandert nooit. Vertak daarop en niet op de zin.

Goed antwoordjson

{
  "gegevens": ...,
  "gemeten_op": "2026-08-26T04:12:07.331Z"
}

Foutantwoordjson

{
  "fout": "onbekende_sleutel",
  "uitleg": "Deze sleutel bestaat niet of is ingetrokken. Maak een nieuwe in je dashboard."
}

Limieten

60 verzoeken per minuut per sleutel. Elk antwoord draagt twee kopregels: X-Vermeld-Limiet en X-Vermeld-Resterend. Zo hoef je niet op een 429 te wachten om te weten dat je moet afremmen.

Ga je eroverheen, dan krijg je status 429 met te_veel_verzoeken. De teller staat per minuut, dus wachten helpt altijd.

Kopregels van een antwoordhttp

HTTP/2 200
content-type: application/json
x-vermeld-limiet: 60
x-vermeld-resterend: 59
cache-control: no-store

Fouten

Een fout heeft altijd een HTTP-status en een vaste code. Dit zijn ze allemaal.

Code	Uitleg
`geen_sleutel`HTTP 401	Er zat geen geldige Authorization-kopregel bij.
`onbekende_sleutel`HTTP 401	De sleutel bestaat niet of is ingetrokken.
`pakket_zonder_api`HTTP 403	Je pakket heeft de API niet. Ze zit in Groei en Bureau.
`onbekend_project`HTTP 404	Dit project bestaat niet. Of het hoort niet bij deze sleutel. Wij maken daar met opzet geen verschil tussen: anders vertelt de API welke id’s bestaan.
`te_veel_verzoeken`HTTP 429	Meer dan 60 verzoeken in deze minuut met deze sleutel. Wacht tot de volgende minuut.

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten

Antwoordjson

{
  "fout": "geen_sleutel",
  "uitleg": "Stuur je sleutel mee als Authorization: Bearer vm_live_..."
}

Websites

GET /api/v1/projecten

Je websites. Begin hier: de id's uit deze lijst gaan in de andere routes.

Parameters

Geen. De sleutel bepaalt welke websites je terugkrijgt.

Velden

gegevens is een lijst. Elk element heeft deze velden.

Veld	Uitleg
`id`string	De vaste id van de website. Die gaat in het pad van elke andere route.
`domein`string	Het domein van de website.
`merknaam`string \| null	De merknaam waarop wij zoeken. Null als er geen is ingevuld.
`aangemaakt_op`string	Wanneer de website werd toegevoegd. ISO 8601 in UTC.

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": [
    {
      "id": "6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18",
      "domein": "bakkerijjan.be",
      "merknaam": "Bakkerij Jan",
      "aangemaakt_op": "2026-03-04T09:11:22.000Z"
    }
  ],
  "gemeten_op": null
}

Vermeldscore

GET /api/v1/projecten/{id}/score

De Vermeldscore en de vier onderdelen, met hun gewicht.

Parameters

Parameter	Uitleg
`id`string · verplicht · in het pad	De id van een website. Je haalt hem op met de route projecten.

Velden

gegevens is één object met deze velden.

Veld	Uitleg
`domein`string	Het domein van de website.
`score`integer \| null	De Vermeldscore, van 0 tot 100. Null zolang er geen doorlichting klaar is.
`onderdelen`array	De vier onderdelen van de score. Altijd alle vier.
`onderdelen[].sleutel`string	aanwezigheid, citeerbaarheid, entiteit of agent. Vertak hierop.
`onderdelen[].naam`string	De naam van het onderdeel. Altijd in het Nederlands.
`onderdelen[].gewicht`integer	Het gewicht in de score. Samen tellen ze tot 100.
`onderdelen[].score`integer \| null	Van 0 tot 100. Null als dit onderdeel niet gemeten is.

Mogelijke fouten

401geen_sleutel
401onbekende_sleutel
403pakket_zonder_api
404onbekend_project
429te_veel_verzoeken

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten/6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18/score \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": {
    "domein": "bakkerijjan.be",
    "score": 61,
    "onderdelen": [
      {
        "sleutel": "aanwezigheid",
        "naam": "Aanwezigheid",
        "gewicht": 40,
        "score": 45
      },
      {
        "sleutel": "citeerbaarheid",
        "naam": "Citeerbaarheid",
        "gewicht": 25,
        "score": 72
      },
      {
        "sleutel": "entiteit",
        "naam": "Entiteit",
        "gewicht": 20,
        "score": 80
      },
      {
        "sleutel": "agent",
        "naam": "Agent-klaar",
        "gewicht": 15,
        "score": null
      }
    ]
  },
  "gemeten_op": "2026-08-26T04:12:07.331Z"
}

Zichtbaarheid

GET /api/v1/projecten/{id}/zichtbaarheid

De vier metrieken, in het geheel en per kanaal. Alleen de jongste meting per vraag per kanaal telt mee: anders meet je je eigen meetritme.

Parameters

Parameter	Uitleg
`id`string · verplicht · in het pad	De id van een website. Je haalt hem op met de route projecten.

Velden

gegevens is één object met deze velden.

Veld	Uitleg
`domein`string	Het domein van de website.
`vermeldingsgraad`integer \| null	In hoeveel procent van de geslaagde metingen je naam in het antwoord staat. Null zonder geslaagde meting.
`citatiegraad`integer \| null	In hoeveel procent van de geslaagde metingen een eigen pagina als bron onder het antwoord staat. Nooit hoger dan de vermeldingsgraad.
`gemiddelde_positie`integer \| null	Waar je naam gemiddeld valt: 0 is helemaal vooraan, 100 achteraan. Alleen over antwoorden waarin je genoemd wordt.
`toonverdeling`object	Hoe vaak elke toon voorkwam: positief, neutraal of negatief.
`aandeel_in_de_stem`object	Wie welk deel van alle vermeldingen pakt, in procent. Jijzelf staat onder jij. Samen 100. Leeg zolang niemand genoemd werd.
`per_kanaal`array	Dezelfde cijfers per kanaal.
`per_kanaal[].kanaal`string	Het kanaal, zoals chatgpt of perplexity.
`per_kanaal[].gemeten`integer	Het aantal geslaagde metingen op dit kanaal.
`per_kanaal[].vermeldingsgraad`integer \| null	Zoals hierboven, voor dit kanaal.
`per_kanaal[].citatiegraad`integer \| null	Zoals hierboven, voor dit kanaal.
`per_kanaal[].gemiddelde_positie`integer \| null	Zoals hierboven, voor dit kanaal.

Mogelijke fouten

401geen_sleutel
401onbekende_sleutel
403pakket_zonder_api
404onbekend_project
429te_veel_verzoeken

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten/6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18/zichtbaarheid \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": {
    "domein": "bakkerijjan.be",
    "vermeldingsgraad": 38,
    "citatiegraad": 12,
    "gemiddelde_positie": 64,
    "toonverdeling": {
      "positief": 7,
      "neutraal": 4
    },
    "aandeel_in_de_stem": {
      "jij": 22,
      "Bakkerij Peeters": 41,
      "Bakkerij Wouters": 37
    },
    "per_kanaal": [
      {
        "kanaal": "chatgpt",
        "gemeten": 25,
        "vermeldingsgraad": 44,
        "citatiegraad": 16,
        "gemiddelde_positie": 58
      }
    ]
  },
  "gemeten_op": "2026-08-26T04:12:07.331Z"
}

Vragen

GET /api/v1/projecten/{id}/vragen

De vragen die wij stellen, met hun jongste uitslag per kanaal. Het ruwe antwoord zit er niet in: dat is tekst van een derde partij en het maakt het antwoord tien keer zo groot.

Parameters

Parameter	Uitleg
`id`string · verplicht · in het pad	De id van een website. Je haalt hem op met de route projecten.

Velden

gegevens is een lijst. Elk element heeft deze velden.

Veld	Uitleg
`id`string	De vaste id van de vraag.
`vraag`string	De vraag zoals wij ze aan de assistenten stellen.
`label`string \| null	Het soort vraag: keuzehulp, lokaal, prijs, probleem of merk. Null als er geen is.
`laatst_gemeten_op`string \| null	Wanneer deze vraag het laatst gemeten werd. Null als dat nog niet gebeurde.
`kanalen`array	De jongste meting per kanaal.
`kanalen[].kanaal`string	Het kanaal, zoals chatgpt of perplexity.
`kanalen[].genoemd`boolean \| null	Of je naam in het antwoord staat. Null als de meting niet gelukt is.
`kanalen[].geciteerd`boolean \| null	Of een eigen pagina als bron onder het antwoord staat. Null als de meting niet gelukt is.
`kanalen[].positie`integer \| null	Waar je naam valt, van 0 tot 100. Null als je naam niet in de tekst staat.
`kanalen[].toon`string \| null	positief, neutraal of negatief. Null zonder oordeel.
`kanalen[].status`string	gelukt, mislukt, overgeslagen of geen_antwoord. Bij geen_antwoord toonde het kanaal op deze vraag geen AI-antwoord.
`kanalen[].gemeten_op`string	Wanneer deze meting liep.

Mogelijke fouten

401geen_sleutel
401onbekende_sleutel
403pakket_zonder_api
404onbekend_project
429te_veel_verzoeken

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten/6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18/vragen \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": [
    {
      "id": "9a41c0b2-5d7e-4f18-a3c6-2b8e1f0d9c47",
      "vraag": "beste bakker in Leuven",
      "label": "lokaal",
      "laatst_gemeten_op": "2026-08-26T04:09:55.000Z",
      "kanalen": [
        {
          "kanaal": "chatgpt",
          "genoemd": true,
          "geciteerd": false,
          "positie": 41,
          "toon": "positief",
          "status": "gelukt",
          "gemeten_op": "2026-08-26T04:09:55.000Z"
        }
      ]
    }
  ],
  "gemeten_op": "2026-08-26T04:09:55.000Z"
}

Concurrenten

GET /api/v1/projecten/{id}/concurrenten

Wie er naast je genoemd wordt. Alleen namen die wij zelf in een antwoord zagen staan.

Parameters

Parameter	Uitleg
`id`string · verplicht · in het pad	De id van een website. Je haalt hem op met de route projecten.

Velden

gegevens is een lijst. Elk element heeft deze velden.

Veld	Uitleg
`naam`string	De naam van de concurrent.
`domein`string \| null	Zijn domein. Null als wij het niet kennen.
`vermeldingen`integer	Hoe vaak wij hem in een antwoord zagen staan.
`eerst_gezien_op`string	Wanneer wij hem voor het eerst zagen.
`laatst_gezien_op`string	Wanneer wij hem het laatst zagen.
`bron`string	gevonden als wij hem zelf in een antwoord zagen. handmatig als jij hem toevoegde.

Mogelijke fouten

401geen_sleutel
401onbekende_sleutel
403pakket_zonder_api
404onbekend_project
429te_veel_verzoeken

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten/6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18/concurrenten \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": [
    {
      "naam": "Bakkerij Peeters",
      "domein": "bakkerijpeeters.be",
      "vermeldingen": 34,
      "eerst_gezien_op": "2026-04-02T00:00:00.000Z",
      "laatst_gezien_op": "2026-08-26T04:09:55.000Z",
      "bron": "gevonden"
    }
  ],
  "gemeten_op": "2026-08-26T04:09:55.000Z"
}

Werkpunten

GET /api/v1/projecten/{id}/werkpunten

De openstaande bevindingen van je jongste doorlichting. Met herkomst erbij: dat veld zegt welke regel deze bevinding voorschrijft.

Parameters

Parameter	Uitleg
`id`string · verplicht · in het pad	De id van een website. Je haalt hem op met de route projecten.

Velden

gegevens is een lijst. Elk element heeft deze velden.

Veld	Uitleg
`id`string	De vaste id van het werkpunt.
`onderdeel`string \| null	Bij welk onderdeel van de score het hoort: aanwezigheid, citeerbaarheid, entiteit of agent. Null als het bij geen onderdeel hoort.
`categorie`string	De groep van de controle, zoals ai.
`ernst`string	kritiek, hoog, gemiddeld, laag of info.
`titel`string	Wat er mis is, in één zin. Volgt je Accept-Language.
`bewijs`string \| null	Wat wij zagen. Null als er niets te tonen is.
`advies`string \| null	Wat je eraan doet. Null als er geen advies is.
`pagina`string \| null	Het adres van de bron waarop dit advies steunt. Null als er geen is.
`herkomst`string \| null	Welke regel deze drempel voorschrijft. Null als de drempel van ons komt.

Mogelijke fouten

401geen_sleutel
401onbekende_sleutel
403pakket_zonder_api
404onbekend_project
429te_veel_verzoeken

Verzoekbash

curl https://www.vermeld.be/api/v1/projecten/6f2c1d4e-8b3a-4c55-9e21-0d7a4b9c3e18/werkpunten \
  -H "Authorization: Bearer vm_live_..."

Antwoordjson

{
  "gegevens": [
    {
      "id": "3c88a9e2-1f4b-4d6a-8c07-5e9b2d1a7f30",
      "onderdeel": "agent",
      "categorie": "ai",
      "ernst": "kritiek",
      "titel": "GPTBot wordt geweigerd in robots.txt",
      "bewijs": "User-agent: GPTBot / Disallow: /",
      "advies": "Haal de regel weg of beperk hem tot /admin.",
      "pagina": "https://platform.openai.com/docs/bots",
      "herkomst": null
    }
  ],
  "gemeten_op": "2026-08-26T04:12:07.331Z"
}

MCP-server

Dezelfde zes routes bestaan ook als MCP-server. Dan leest je AI-assistent je cijfers zelf. Dezelfde sleutel, dezelfde grenzen en hetzelfde antwoord als hierboven. Elk bericht aan de server telt mee voor de limiet.

In Claude Code voeg je hem toe met één opdracht. Een andere client, zoals Cursor, krijgt het adres en de kopregel in zijn instellingen.

Een client die alleen met OAuth aanmeldt en geen eigen kopregel laat instellen, werkt nog niet. Wij hebben geen OAuth.

De tools heten zoals de routes. Alle tools behalve projecten vragen een project_id.

Tool	Uitleg
`projecten`	Websites
`score`project_id: string · verplicht	Vermeldscore
`zichtbaarheid`project_id: string · verplicht	Zichtbaarheid
`vragen`project_id: string · verplicht	Vragen
`concurrenten`project_id: string · verplicht	Concurrenten
`werkpunten`project_id: string · verplicht	Werkpunten

Claude Codebash

claude mcp add --transport http vermeld https://www.vermeld.be/api/mcp \
  --header "Authorization: Bearer vm_live_..."

Andere clientsjson

{
  "mcpServers": {
    "vermeld": {
      "url": "https://www.vermeld.be/api/mcp",
      "headers": {
        "Authorization": "Bearer vm_live_..."
      }
    }
  }
}