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.

Authenticatie

Om HTTP-verzoeken naar ons systeem te authoriseren gebruiken we een zogeheten long lived Bearer token.

Voorbeeld van Authorization-header met een Bearer-token:

Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0

Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0

Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0

De endpoints zijn per klant beschikbaar onder een eigen sub-domein, bijvoorbeeld:

https://{klant}.vragen.ai/api/v1/

https://{klant}.vragen.ai/api/v1/

https://{klant}.vragen.ai/api/v1/

De API verwacht bij elke request de volgende headers:

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Search-endpoints

Er zijn twee search-endpoints beschikbaar:

1. Zoeken in documenten

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

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

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

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

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

?query=openingstijden gemeentehuis

?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

?query=vergunning&maxDistance=0.4

?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

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

?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

?query=jaarverslag&sort=-date,title

?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

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

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

Voor document-chunks/search gebruik je bijvoorbeeld:

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

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

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

Je kunt ook direct het interne resource type gebruiken:

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

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

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

GET https://{klant}.vragen.ai/api/v1/documents/search?query=homepage&filter[0][path]=author&filter[0][operator]==&filter[0][value]=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

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

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

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

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

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

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

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

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"
      }
    }
  ]
}

{
  "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"
      }
    }
  ]
}

{
  "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.

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

Aan de hand van bovenstaande informatie en voorbeelden zou je geen problemen moeten ondervinden om een verbinding op te zetten met onze API search-endpoints. Als je nog vragen hebt, neem dan contact op met ons supportteam via info@vragen.ai.