Search via the API
As a supplement to the CRUD endpoints for Documents, our JSON:API also provides search endpoints. With these endpoints, you can search semantically within your knowledge base and further refine the results with filters, facets, sorting, and pagination.
These search endpoints are intended for situations where it is not enough to retrieve a document by ID, but where you want to find relevant documents or document fragments based on a search query.
Authentication
To authorize HTTP requests to our system, we use a so-called long lived Bearer token.
Example of an Authorization header with a Bearer token:
The endpoints are available per customer under their own subdomain, for example:
The API expects the following headers with every request:
Search endpoints
There are two search endpoints available:
1. Search in documents
This endpoint returns search results at document level. Each result refers to a document from the knowledge base.
2. Search in document fragments
This endpoint returns search results at chunk level. A chunk is a fragment of a document. This endpoint is useful when you want to receive more fine-grained search results than at full document level.
Although the source differs, both endpoints have the same request and response structure.
General request parameters
The following query parameters are supported:
query
Type: string
Optional
The natural-language search question or search term on which semantic search is performed.
Example:
maxDistance
Type: number
Optional
Value: between 0 and 1
This lets you limit the maximum semantic distance of results. A lower value makes the search stricter.
Example:
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:
sort
Type: string
Optional
Sort fields are specified comma-separated. Use:
veldnaamfor ascending sort-veldnaamfor descending sort+veldnaamexplicitly for ascending sort
Example:
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 use, for example:
For document-chunks/search you use, for example:
You can also use the internal resource type directly:
Note: the response internally uses the resource type semantic-searchables, but the API also accepts the aliases documents and document-chunks in fields[...] for these endpoints.
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 onvalue: the value being searched foroperator: the comparison operatorid: optional, for grouped filtersparent: optional, to link filters to a grouptagortags: optional, to label filters
Available filter operators:
=!=>>=<<=LIKEINALLNOT INIS NULL
Boolean operators are available for filter groups:
ANDOR
Which path values can you use?
The available filter fields depend on how the customer's knowledge base is set up. In practice, this includes:
metadata fields from
meta_dataknowledge scope fields
system fields, such as
source
Note:
metadata keys are stored internally in
snake_casea metadata field such as
publishDatetherefore becomespublish_date, for example
Simple filter example
Search only within documents whose metadata author equals SWIS:
Filter example with list values
Search within documents that fall into one of multiple categories:
Filter example with groups
Search for documents where:
source = websiteAND (
category = faqORcategory = manual)
Facets
With facets, you can return aggregations 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 bylimit: maximum number of bucketsmin_count: minimum number of results per bucketoperator:ANDorORexclude_tags: optional, to exclude filters with the same tags during facet calculation
Example:
In the response, facet results are included under meta.facets.
Example request
The example below searches semantically in documents, limits the results to source website, requests facets for category, and sorts descending by date.
Example response
The search endpoints return results as a JSON:API collection with resource type semantic-searchables.
Meaning of response fields
summary
In documents/search, this field contains a summary or representative content of the document.
In document-chunks/search, this field contains the content of the specific document fragment 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 the query and the 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.
Practical considerations
Use
documents/searchwhen you want to display results at document level.Use
document-chunks/searchwhen you want to display the most relevant text fragment right away.Keep
snake_casein 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 respective customer is set up.
Support
Based on the information and examples above, you should have no trouble setting up a connection to our API search endpoints. If you still have questions, please contact our support team at info@vragen.ai.
