Docs / API

Zoeken via de API

Als aanvulling op de CRUD-endpoints voor Documenten zijn er binnen onze JSON:API ook search-endpoints beschikbaar. Met deze endpoints kun je semantisch zoeken binnen je kennisbank en de resultaten verder verfijnen met filters, facets, sortering en paginering.

Deze search-endpoints zijn bedoeld voor situaties waarin het niet genoeg is om een document op ID op te halen, maar waarbij je relevante documenten of documentfragmenten wilt terugvinden op basis van een zoekvraag.

Voordat je begint

De base-URL, de authenticatie met een Bearer-token en de vereiste headers staan op Werken met de API. De endpoints hieronder gaan daarvan uit.

Search-endpoints

Er zijn drie search-endpoints beschikbaar:

1. Zoeken in documenten

GET https://{klant}.vragen.ai/api/v1/documents/search

Dit endpoint geeft zoekresultaten terug op documentniveau. Ieder resultaat verwijst naar een document uit de kennisbank.

2. Zoeken in documentfragmenten

GET https://{klant}.vragen.ai/api/v1/document-chunks/search

Dit endpoint geeft zoekresultaten terug op chunkniveau. Een chunk is een fragment van een document. Dit endpoint is bruikbaar wanneer je fijnmaziger zoekresultaten wilt ontvangen dan op volledig documentniveau.

Hoewel de bron verschilt, hebben deze twee endpoints dezelfde request- en response-structuur.

3. Zoeken via een zoekstrategie

GET https://{klant}.vragen.ai/api/v1/search-strategies/{id}/search

Dit endpoint zoekt met een zoekstrategie uit je omgeving: dezelfde stappen die je agent gebruikt om kennis op te halen (de vraag herschrijven, hybride zoeken, herrangschikken), maar zonder gegenereerd antwoord. Je krijgt resultaten op documentniveau terug, in de volgorde die de strategie bepaalt. Zo zoekt je eigen site precies zoals je agent dat doet, en kun je het zoeken bijsturen in de app zonder iets aan je koppeling te veranderen.

Welke strategieën er zijn, vraag je op met GET https://{klant}.vragen.ai/api/v1/search-strategies: per strategie het id, de name, een description en of het de standaardstrategie is (is_default). Voor beide endpoints heeft je token de permissie search-strategies:read nodig.

De parameters query, maxDistance, filter[...], fields[...], page[offset] en page[limit] werken hier hetzelfde als hieronder beschreven, en de response heeft dezelfde structuur. Bij paginering is er één verschil: de strategie bepaalt zelf hoeveel resultaten ze ophaalt, en door die verzameling blader je. meta.total geeft dus het aantal resultaten van de strategie, en met page[offset] en page[limit] haal je daar steeds een stuk uit. Facetten worden op dit endpoint niet ondersteund; die horen bij de eerste twee endpoints.

Wil je voor één verzoek afwijken van wat de strategie zelf instelt, bijvoorbeeld om een instelling te vergelijken zonder de strategie in de app aan te passen, dan zijn er naast maxDistance nog drie parameters:

• alpha (0–1): de balans tussen trefwoordzoeken en semantisch zoeken in de zoekstappen van de strategie.
• minRelevanceScore (of de oudere naam relevanceCutoff): resultaten met een lagere relevantiescore vallen af.
• enableReranking=false: slaat het herrangschikken van de strategie over voor dit verzoek.

Algemene request-parameters

De volgende queryparameters worden ondersteund:

query

Type: string
Optioneel

De natuurlijke zoekvraag of zoekterm waarop semantisch gezocht wordt.

Voorbeeld:

?query=openingstijden gemeentehuis

maxDistance

Type: number
Optioneel
Waarde: tussen 0 en 1

Hiermee beperk je de maximale semantische afstand van resultaten. Een lagere waarde maakt de zoekopdracht strenger.

Voorbeeld:

?query=vergunning&maxDistance=0.4

page[offset]

Type: integer
Optioneel
Standaard: 0

Het aantal resultaten dat moet worden overgeslagen.

page[limit]

Type: integer
Optioneel
Standaard: door het platform bepaald

Het maximale aantal resultaten dat moet worden teruggegeven.

Voorbeeld:

?query=verlof&page[offset]=0&page[limit]=25

sort

Type: string
Optioneel

Sorteervelden worden komma-gescheiden opgegeven. Gebruik:

• veldnaam voor oplopende sortering

• -veldnaam voor aflopende sortering

• +veldnaam expliciet voor oplopende sortering

Voorbeeld:

?query=jaarverslag&sort=-date,title

Welke sorteerbare velden beschikbaar zijn hangt af van de velden die voor de kennisbank zijn ingericht.

fields[...]

Type: sparse fieldset
Optioneel

Hiermee kun je het aantal responsevelden beperken.

Voor documents/search gebruik je bijvoorbeeld:

fields[documents]=id,url,title,summary

Voor document-chunks/search gebruik je bijvoorbeeld:

fields[document-chunks]=id,url,summary

Je kunt ook direct het interne resource type gebruiken:

fields[semantic-searchables]=id,url,title,summary

Let op: de response gebruikt intern het resource type semantic-searchables, maar de API accepteert voor deze endpoints ook de aliassen documents en document-chunks in fields[...].

Filters

Met filter kun je zoekresultaten beperken tot documenten of chunks die voldoen aan extra voorwaarden.

De filters worden als array van objecten meegegeven. Iedere filterregel ondersteunt onder andere:

• path: de naam van het veld waarop je wilt filteren

• value: de gezochte waarde

• operator: de vergelijkingsoperator

• id: optioneel, voor gegroepeerde filters

• parent: optioneel, om filters aan een groep te koppelen

• tag of tags: optioneel, om filters te labelen

Beschikbare filteroperators:

• =

• !=

• >

• >=

• <

• <=

• LIKE

• IN

• ALL

• NOT IN

• IS NULL

Voor filtergroepen zijn de boolean-operators beschikbaar:

• AND

• OR

Welke path-waarden kun je gebruiken?

De beschikbare filtervelden hangen af van de inrichting van de kennisbank van de klant. In de praktijk gaat het om:

• metadata-velden uit meta_data

• knowledge scope-velden

• systeemvelden, zoals source

Let op:

• metadata-sleutels worden intern opgeslagen in snake_case

• een metadata-veld zoals publishDate wordt daardoor bijvoorbeeld publish_date

Eenvoudig filtervoorbeeld

Zoek alleen binnen documenten waarvan de metadata author gelijk is aan SWIS:

GET https://{klant}.vragen.ai/api/v1/documents/search?query=homepage&filter[0][path]=author&filter[0][operator]==&filter[0][value]=SWIS

Filtervoorbeeld met lijstwaarden

Zoek binnen documenten die in een van meerdere categorieen vallen:

GET https://{klant}.vragen.ai/api/v1/documents/search?query=beleid&filter[0][path]=category&filter[0][operator]=IN&filter[0][value][]=beleid&filter[0][value][]=nieuws

Filtervoorbeeld met groepen

Zoek op documenten waarbij:

• source = website

• EN (category = faq OF category = handleiding)

GET https://{klant}.vragen.ai/api/v1/documents/search?query=wachtwoord&filter[0][id]=group_root&filter[0][operator]=AND&filter[1][path]=source&filter[1][operator]==&filter[1][value]=website&filter[2][id]=group_categories&filter[2][parent]=group_root&filter[2][operator]=OR&filter[3][parent]=group_categories&filter[3][path]=category&filter[3][operator]==&filter[3][value]=faq&filter[4][parent]=group_categories&filter[4][path]=category&filter[4][operator]==&filter[4][value]=handleiding

Facets

Met facets kun je aggregaties laten teruggeven naast de zoekresultaten. Dit is nuttig voor filters in een zoekinterface, zoals aantallen per categorie, auteur of bron.

Iedere facetregel ondersteunt:

• path: het veld waarop gegroepeerd moet worden

• limit: maximaal aantal buckets

• min_count: minimaal aantal resultaten per bucket

• operator: AND of OR

• exclude_tags: optioneel, om filters met dezelfde tags uit te sluiten bij facetberekening

Voorbeeld:

GET https://{klant}.vragen.ai/api/v1/documents/search?query=parkeren&facets[0][path]=category&facets[0][limit]=5&facets[0][min_count]=1&facets[1][path]=source&facets[1][limit]=10

In de response worden facetresultaten opgenomen onder meta.facets.

Voorbeeld request

Onderstaand voorbeeld zoekt semantisch in documenten, beperkt de resultaten tot bron website, vraagt facets op voor category en sorteert aflopend op date.

GET https://{klant}.vragen.ai/api/v1/documents/search?query=duurzaamheid&maxDistance=0.5&filter[0][path]=source&filter[0][operator]==&filter[0][value]=website&facets[0][path]=category&facets[0][limit]=10&sort=-date&page[offset]=0&page[limit]=10

Voorbeeld response

De search-endpoints geven resultaten terug als JSON:API-collectie met resource type semantic-searchables.

{
  "meta": {
    "total": 2,
    "limit": 10,
    "offset": 0,
    "facets": {
      "category": [
        {
          "filter": "handleiding",
          "count": 8
        },
        {
          "filter": "faq",
          "count": 3
        }
      ]
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://{klant}.vragen.ai/api/v1/documents/search"
  },
  "data": [
    {
      "type": "semantic-searchables",
      "id": "9001",
      "attributes": {
        "url": "https://www.domein-met-het-nieuwe-zoeken.nl/duurzaamheid",
        "favicon": "https://www.domein-met-het-nieuwe-zoeken.nl/favicon.ico",
        "summary": "Samenvatting of relevante inhoud van het gevonden resultaat.",
        "title": "Duurzaamheid",
        "external_reference": "scrapedPage:9001",
        "last_updated": "2026-05-15T12:00:00+00:00",
        "relevance_score": 0.92,
        "distance": 0.08,
        "knowledge_scopes": {
          "topic": "duurzaamheid"
        },
        "metadata_fields": {
          "category": "handleiding",
          "author": "Gemeente Voorbeeld"
        },
        "mime_type": "text/html"
      }
    }
  ]
}

Betekenis van responsevelden

summary

Bij documents/search bevat dit veld een samenvatting of representatieve inhoud van het document.

Bij document-chunks/search bevat dit veld de inhoud van het specifieke documentfragment dat als resultaat is gevonden.

relevance_score

Een score die aangeeft hoe relevant het resultaat is voor de zoekopdracht.

distance

De semantische afstand tussen query en resultaat. Lager is doorgaans beter.

metadata_fields

De metadata die bij het document hoort, voor zover beschikbaar.

knowledge_scopes

De knowledge scopes die aan het document gekoppeld zijn, voor zover beschikbaar.

Vergelijkbare content (more like this)

Naast zoeken op een zoekvraag kun je vergelijkbare content opvragen: documenten of fragmenten die lijken op een document dat je al kent. Denk aan een blok "Lees ook" onder een artikel, waarmee je lezer doorklikt naar verwante pagina's. Er zijn drie endpoints:

GET https://{klant}.vragen.ai/api/v1/documents/similar
GET https://{klant}.vragen.ai/api/v1/document-chunks/similar
GET https://{klant}.vragen.ai/api/v1/search-strategies/{id}/similar

Het verschil met zoeken zit in de query-parameter. Bij similar is dat geen zoekterm, maar de referentie van het bron-document waarvan je vergelijkbare content wilt. Je mag daar de id, de external_reference of de uuid van dat document opgeven.

De overige parameters komen overeen met de zoek-endpoints:

• query (verplicht): de referentie van het bron-document.
• distance (optioneel, 0–1): filtert resultaten weg waarvan de semantische afstand te groot is. Lager is strenger.
• filter[...] en facets[...]: werken hetzelfde als bij zoeken.
• page[offset] en page[limit]: paginering.

De response heeft dezelfde structuur als bij de zoek-endpoints.

GET https://{klant}.vragen.ai/api/v1/documents/similar?query=scrapedPage:9001&distance=0.5&page[limit]=10

Vergelijkbare content via een zoekstrategie

Met search-strategies/{id}/similar loopt "meer zoals dit" door een zoekstrategie uit je omgeving. De vaste filters, de metadata-boost en het herrangschikken uit die strategie gelden dan ook hier, net als bij je agent. Wil je de aanbevelingen op je site anders afstemmen, dan pas je de strategie aan in de app; je koppeling blijft hetzelfde.

Dit endpoint vergelijkt altijd hele documenten. Stappen die met de tekst van een vraag werken, zoals herschrijven of opsplitsen, slaat het over, want er is geen vraag. In de bouwer van de strategie staan die stappen gemarkeerd met Genegeerd bij vergelijkbaar.

De parameters query (de id, external_reference of uuid van het bron-document), distance, filter[...], page[offset] en page[limit] werken zoals hierboven. Geef je distance mee, dan vervangt die voor dit verzoek de maximale afstand uit de strategie. Facetten worden op dit endpoint niet ondersteund. Je token heeft de permissie search-strategies:read nodig.

GET https://{klant}.vragen.ai/api/v1/search-strategies/{id}/similar?query=scrapedPage:9001&page[limit]=5

Als het bron-document (nog) niet beschikbaar is

Alle drie de similar-endpoints geven een 404 als het bron-document niet bestaat, uitgeschakeld is of nog niet verwerkt is. Dat laatste gebeurt bijvoorbeeld vlak nadat je een document via de API hebt aangemaakt. Behandel een 404 daarom niet als "er is niets vergelijkbaars" en sla dat ook niet zo op: probeer het later opnieuw. Een lege lijst betekent wél dat er niets vergelijkbaars gevonden is.

Praktische aandachtspunten

• Gebruik documents/search wanneer je resultaten op documentniveau wilt tonen.

• Gebruik document-chunks/search wanneer je direct het meest relevante tekstfragment wilt tonen.

• Houd rekening met snake_case bij metadata-velden in filters en facets.

• Niet ieder zichtbaar responseveld is automatisch filterbaar of sorteerbaar.

• Welke filter-, facet- en sorteervelden beschikbaar zijn, hangt af van de inrichting van de kennisbank van de betreffende klant.

• Wil je zien waar bezoekers naar zoeken? Zet in je omgeving Zoekopdrachten opslaan aan; iedere zoekopdracht met een zoekvraag via de search-endpoints verschijnt dan onder Inzicht → Zoekopdrachten in de app, met de zoekterm, de herkomst en de resultaten. Verzoeken om vergelijkbare content worden niet vastgelegd. Zie Gesprekken.

Support

Kom je er niet uit? Mail ons supportteam via service@vragen.ai.