Search and filters

Agents search datasources automatically. You can also search them directly, for example to test your data or to build your own search feature.

Search endpoints

Endpoint	Use it for
`GET /api/v1/retrieve`	Semantic search by meaning
`GET /api/v1/retrieve_with_rerank`	Semantic search where the best candidates are ranked again for higher precision
`GET /api/v1/retrieve_hybrid`	Combined semantic and keyword search. Good for part numbers, error codes and other exact terms.
`POST /api/v1/data/datasources/{name}/filters`	Find content by metadata only, without a search text. See Filter by metadata only.

Parameters

Parameter	Endpoints	Description
`search`	All	The search text
`datasources`	All	Comma-separated datasource names
`similarity_top_k`	All	Number of results, or of candidates for reranking and hybrid search
`metadata_filters`	All	Optional RQL filter, see below
`search_context`	Rerank	Additional context for ranking, for example the user’s previous question
`rerank_top_n`	Rerank	Number of results returned after reranking
`sparse_top_k`	Hybrid	Number of keyword candidates

Example:

GET /api/v1/retrieve_hybrid?search=error%20E23%20CAM-45&datasources=ProductManuals&similarity_top_k=5&sparse_top_k=5
Authorization: Bearer ${SQE_TOKEN}
X-Tenant-ID: ${TENANT_ID}

Metadata filters

Filters use RQL expressions on document metadata:

Expression	Matches
`eq(device_model, "CAM-45")`	Equal
`gt(date, "2025-01-01")`	Greater than
`in(category, ["hardware", "software"])`	One of several values
`and(eq(device_model, "CAM-45"), eq(document_type, "manual"))`	All conditions
`or(eq(error_code, "E23"), eq(error_code, "E24"))`	Any condition

Filters only work well if metadata is consistent. See Ingestion best practices.

Filter by metadata only

When you know exactly which attributes you are looking for, you do not need a semantic search. The filter endpoint returns the nodes of one datasource whose metadata matches an RQL expression:

POST /api/v1/data/datasources/ProductManuals/filters?metadata_filters=and(eq(device_model,"CAM-45"),eq(document_type,"manual"))&top_k=20&sort=-page_number
Authorization: Bearer ${SQE_TOKEN}
X-Tenant-ID: ${TENANT_ID}

Parameter	Description
`metadata_filters`	Required. RQL expression, see Metadata filters.
`top_k`	Maximum number of nodes. Default: 10.
`sort`	Optional. Comma-separated metadata fields. Prefix a field with `-` for descending order, for example `-created`.

URL-encode the query parameters in your client.

Typical uses:

List the latest documents of a type, for example the five most recent shift reports.
Check which content exists for a device or a plant after loading data.
Retrieve content by an exact attribute, for example a ticket number, where meaning does not matter.

The caller needs access to the datasource. See Roles and permissions.

Which search to use

Situation	Recommended
Natural language questions	`retrieve`
Many similar documents, precision matters	`retrieve_with_rerank`
Questions with codes, IDs or exact product names	`retrieve_hybrid`
A known subset of documents	Any endpoint with `metadata_filters`
Exact attributes, no search text	The filter endpoint