Search via the API
In addition to the CRUD endpoints for Documents, search endpoints are also available within our JSON:API. With these endpoints you can perform semantic searches within your knowledge base and further refine the results with filters, facets, sorting, and pagination.
These search endpoints are designed for situations where simply retrieving a document by ID is not enough, 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 each request:
Search endpoints
There are two search endpoints available:
1. Search in documents
This endpoint returns search results at the document level. Each result refers to a document from the knowledge base.
2. Search in document fragments
This endpoint returns search results at the chunk level. A chunk is a fragment of a document. This endpoint is useful when you want to retrieve more granular search results than at the full document level.
Although the source differs, both endpoints share the exact same request and response structure.
General request parameters
The following query parameters are supported:
query
Type: string
Optional
The natural language query or search term used for semantic searching.
Example:
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:
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
Sorting fields are specified as comma-separated values. Use:
fieldnamefor ascending sort-fieldnamefor descending sort+fieldnameexplicitly for ascending sort
Example:
Which sortable fields are available depends on the fields configured for the knowledge base.
fields[...]
Type: sparse fieldset
Optional
This allows you to limit the response fields.
For example, for documents/search you use:
For example, for document-chunks/search you use:
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
Using filter you can narrow down search results to documents or chunks that meet additional conditions.
Filters are provided as an array of objects. Each filter rule supports options including:
path: the name of the field you want to filter onvalue: the value you are looking 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 the setup of the client's knowledge base. In practice, these include:
metadata fields from
meta_dataknowledge scope fields
system fields, such as
source
Note:
metadata keys are stored internally in
snake_casea metadata field like
publishDatetherefore becomespublish_date
Simple filter example
Search only within documents where the metadata author is equal to 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
Using facets allows you to return aggregations alongside search results. This is useful for filter interfaces in search flows, 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 in meta.facets.
Example request
The example below searches semantically in documents, limits results to the source website, requests facets for category, and sorts descending by date.
Example response
The search endpoints return results as a JSON:API collection with the resource type semantic-searchables.
Meaning of response fields
summary
For documents/search, this field contains a summary or representative snippet of the document.
For document-chunks/search, this field contains the text of the specific document fragment found as a search 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 generally 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 show results at the document level.Use
document-chunks/searchwhen you want to show the most relevant text fragment directly.Keep
snake_casein mind for metadata fields in filters and facets.Not every visible response field is automatically filterable or sortable.
The available filter, facet, and sort fields depend on the configuration of the respective client's knowledge base.
Support
Using the information and examples above, you should have no trouble setting up a connection to our API search endpoints. If you have any further questions, please contact our support team at info@vragen.ai.
