Docs API

Searching via the API

In addition to the CRUD endpoints for Documents, our JSON:API also offers search endpoints. With these endpoints you can search your knowledge base semantically and refine the results further with filters, facets, sorting and pagination.

These search endpoints are meant for situations where retrieving a document by ID is not enough, and where you want to find relevant documents or document chunks based on a search query.

Before you start

The base URL, authentication with a Bearer token and the required headers are described on Working with the API. The endpoints below assume this setup.

Search endpoints

Two search endpoints are available:

1. Searching in documents

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

This endpoint returns search results at the document level. Each result refers to a document from the knowledge base.

2. Searching in document chunks

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

This endpoint returns search results at the chunk level. A chunk is a fragment of a document. This endpoint is useful when you want more fine-grained search results than at the full document level.

Although the source differs, both endpoints share the same request and response structure.

General request parameters

The following query parameters are supported:

query

Type: string
Optional

The natural search question or search term used for semantic search.

Example:

?query=town hall opening hours

maxDistance

Type: number
Optional
Value: between 0 and 1

This limits the maximum semantic distance of results. A lower value makes the search stricter.

Example:

?query=permit&maxDistance=0.4

page[offset]

Type: integer
Optional
Default: 0

The number of results to skip.

page[limit]

Type: integer
Optional
Default: determined by the platform

The maximum number of results to return.

Example:

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

sort

Type: string
Optional

Sort fields are provided comma-separated. Use:

  • fieldname for ascending sorting

  • -fieldname for descending sorting

  • +fieldname explicitly for ascending sorting

Example:

?query=annual report&sort=-date,title

Which sortable fields are available depends on the fields configured for the knowledge base.

fields[...]

Type: sparse fieldset
Optional

This lets you limit the number of response fields.

For documents/search you would use, for example:

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

For document-chunks/search you would use, for example:

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

You can also use the internal resource type directly:

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

Please note: the response internally uses the resource type semantic-searchables, but for these endpoints the API also accepts the aliases documents and document-chunks in fields[...].

Filters

With filter you can limit search results to documents or chunks that meet additional conditions.

The filters are passed as an array of objects. Each filter rule supports, among other things:

  • path: the name of the field you want to filter on

  • value: the value to look for

  • operator: the comparison operator

  • id: optional, for grouped filters

  • parent: optional, to attach filters to a group

  • tag or tags: optional, to label filters

Available filter operators:

  • =

  • !=

  • >

  • >=

  • <

  • <=

  • LIKE

  • IN

  • ALL

  • NOT IN

  • IS NULL

For filter groups, the boolean operators are available:

  • AND

  • OR

Which path values can you use?

The available filter fields depend on how the customer's knowledge base is configured. In practice, this involves:

  • metadata fields from meta_data

  • knowledge scope fields

  • system fields, such as source

Please note:

  • metadata keys are stored internally in snake_case

  • a metadata field such as publishDate therefore becomes publish_date, for example

Simple filter example

Search only within documents whose metadata author equals SWIS:

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

Filter example with list values

Search within documents that fall into one of several categories:

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

Filter example with groups

Search for documents where:

  • source = website

  • AND (category = faq OR category = manual)

GET https://{klant}.vragen.ai/api/v1/documents/search?query=password&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]=manual

Facets

With facets you can have aggregations returned alongside the search results. This is useful for filters in a search interface, such as counts per category, author or source.

Each facet rule supports:

  • path: the field to group by

  • limit: maximum number of buckets

  • min_count: minimum number of results per bucket

  • operator: AND or OR

  • exclude_tags: optional, to exclude filters with the same tags when calculating facets

Example:

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

In the response, facet results are included under meta.facets.

Example request

The example below searches documents semantically, limits the results to source website, requests facets for category and sorts descending by date.

GET https://{klant}.vragen.ai/api/v1/documents/search?query=sustainability&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

Example response

The search endpoints return results as a JSON:API collection with resource type semantic-searchables.

{
  "meta": {
    "total": 2,
    "limit": 10,
    "offset": 0,
    "facets": {
      "category": [
        {
          "filter": "manual",
          "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": "Summary or relevant content of the found result.",
        "title": "Sustainability",
        "external_reference": "scrapedPage:9001",
        "last_updated": "2026-05-15T12:00:00+00:00",
        "relevance_score": 0.92,
        "distance": 0.08,
        "knowledge_scopes": {
          "topic": "sustainability"
        },
        "metadata_fields": {
          "category": "manual",
          "author": "Example Municipality"
        },
        "mime_type": "text/html"
      }
    }
  ]
}

Meaning of response fields

summary

For documents/search, this field contains a summary or representative content of the document.

For document-chunks/search, this field contains the content of the specific document chunk that was found as a result.

relevance_score

A score indicating how relevant the result is to the search query.

distance

The semantic distance between query and result. Lower is usually better.

metadata_fields

The metadata associated with the document, where available.

knowledge_scopes

The knowledge scopes linked to the document, where available.

Similar content (more like this)

Besides searching with a search query, you can also request similar content: documents or chunks that resemble a document you already know. There are two endpoints:

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

The difference from searching lies in the query parameter. For similar, this is not a search term, but the reference of the source document for which you want similar content. You can provide the id, the external_reference or the uuid of that document.

The other parameters are the same as for the search endpoints:

  • query (required): the reference of the source document.
  • distance (optional, 0–1): filters out results whose semantic distance is too large. Lower is stricter.
  • filter[...] and facets[...]: work the same as for searching.
  • page[offset] and page[limit]: pagination.

The response has the same structure as the search endpoints.

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

Practical points of attention

  • Use documents/search when you want to display results at the document level.

  • Use document-chunks/search when you want to display the most relevant text fragment directly.

  • Keep snake_case in mind for metadata fields in filters and facets.

  • Not every visible response field is automatically filterable or sortable.

  • Which filter, facet and sort fields are available depends on how the knowledge base of the customer in question is configured.

Support

Stuck? Email our support team at service@vragen.ai.

Didn't find what you were looking for?

Ask your question directly to vragen.ai.

What exactly is vragen.ai?

Example answer by vragen.ai

vragen.ai lets visitors ask their question on your website and gives them a reliable answer straight from your own content, with the source included. You decide which sources the AI uses.

Source: How it works

This is an example. The interactive widget could not load here, for instance because of a script blocker or a slow connection.

Request a demo Try it yourself

You are asking an AI assistant from vragen.ai. Answers come from our own content, with the source included. Why we mention this (Dutch)