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 twee 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 beide endpoints dezelfde request- en response-structuur.

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. Er zijn twee endpoints:

GET https://{klant}.vragen.ai/api/v1/documents/similar
GET https://{klant}.vragen.ai/api/v1/document-chunks/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

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.

Support

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

Niet gevonden wat je zocht?

Stel je vraag direct aan vragen.ai.

Je stelt je vraag aan een AI-assistent van vragen.ai. Antwoorden komen uit onze eigen content, met de bron erbij. Waarom we dit melden

Zoeken via de API

Voordat je begint

Search-endpoints

1. Zoeken in documenten

2. Zoeken in documentfragmenten

Algemene request-parameters

query

maxDistance

page[offset]

page[limit]

sort

fields[...]

Filters

Welke path-waarden kun je gebruiken?

Eenvoudig filtervoorbeeld

Filtervoorbeeld met lijstwaarden

Filtervoorbeeld met groepen

Facets

Voorbeeld request

Voorbeeld response

Betekenis van responsevelden

summary

relevance_score

distance

metadata_fields

knowledge_scopes

Vergelijkbare content (more like this)

Praktische aandachtspunten

Support

Niet gevonden wat je zocht?

`query`

`maxDistance`

`page[offset]`

`page[limit]`

`sort`

`fields[...]`

Welke `path`-waarden kun je gebruiken?

`summary`

`relevance_score`

`distance`

`metadata_fields`

`knowledge_scopes`