Skip to main content
POST
Execute Search
The Search endpoint accepts an optional responseType body field that controls the response format. See Autocomplete → responseType for the comparison; for Search, set it as a JSON body field rather than a query parameter.

​
Full search request example

A real-world search rarely sends just a query. The example below exercises most body parameters at once — pagination, field selection, highlighting, facets, range facets, include/exclude filters, value boosting, sorting, and related searches — with representative values you can adapt.

​
Combining filters and facets (AND / OR)

Faceted search is driven by the filters and notFilters objects. Each key is an indexed field name and each value is an array of values. The way they combine is fixed and predictable:
The top-level operator (AND / OR) is separate from facet filtering. It controls how the words in query are matched against the index — it does not change how filters are combined. Filters always follow the OR-within-field, AND-across-fields rules above.

​
OR within a single field

Return documents in either Documentation or Guides:

​
AND across multiple fields

Return documents that are in Documentation and written in English and published — every field condition must hold:

​
Combining OR within fields and AND across fields

The two rules stack. The request below means: (Documentation OR Guides) AND (en OR da):

​
Excluding values with notFilters

Keep the include filters above but exclude anything that is Archived or Draft (the exclusions are AND-NOT’d onto the result):
Need all words in the query to match and narrow results by facets? Set "operator": "AND" for the text query and add your filters — they work together: the operator tightens the keyword match while filters apply the facet AND/OR logic.

​
Filter value formats

filters, notFilters, and postFilters share the same value grammar. Each key is normally an indexed field name mapped to an array of allowed values. In addition, three reserved keys — range, date, and geo_distance — express numeric ranges, date ranges, and geo-distance filters. Each reserved key takes a flat array of positional arguments, and you can repeat the argument group to add several filters of that type at once.

​
Value

Match a field against one or more exact values (the common facet case):

​
Range (numeric)

Reserved key range, in groups of three: [field, min, max]. Bounds are inclusive (>= / <=); pass an empty string to leave a bound open. Use . as the decimal separator.

​
Date range

Reserved key date, in groups of three: [field, from, to]. Values are ISO 8601 strings; an empty string leaves that side open. Date fields are the indexed date fields (typically _date-suffixed).
Accepted formats include 2017-06-13, 2017-06-13T02:50:25Z, and 2017-06-13T02:50:25+00:00. When no time is given, the whole day is included.

​
Geo distance

Reserved key geo_distance, exactly five items: [field, latitude, longitude, distance, unit]. The field is the _geo_point-suffixed geo field.
unit is one of Inch, Feet, Yards, Miles, NauticalMiles, Kilometers, Meters, Centimeters, Millimeters.
range, date, and geo_distance are reserved keys inside the filter object — you cannot use them as literal field names. All four formats work identically in filters, notFilters, and postFilters.

​
Post-filtering (narrow results without changing facet counts)

filters and notFilters run with the query, so they shape both the ranked results and the Facets counts. postFilters runs after the query as a post-filter: it narrows the documents returned without recomputing the facet counts. This is what powers classic faceted navigation — when a user ticks one value in a facet you want the results to narrow, but the other counts in that facet should stay visible so they can broaden their selection again.
To make post-filters also apply to the returned facet counts, set "enableFacetFiltering": true. postFilters cannot be combined with advancedPostFilter in the same request.

​
Boosting values at query time

Filters decide which documents come back. valueBoost changes what order they come back in: it promotes documents whose field matches values you name, for a single request, without removing anything from the result set. It applies on top of the boosting rules configured on the engine rather than replacing them, so you can tune results per audience or per context without changing engine configuration.
You can boost several fields in one request, and set several weights within a field.

​
Choosing a weight

100 is neutral and leaves ranking unchanged. Raise it to promote: 200 is a moderate lift, 500 a strong one. Start low and increase — a high weight can promote loosely related documents above closely matching ones. Use valueBoost to promote the content you want surfaced. It is not a reliable way to push content down; to remove documents from a result set, use notFilters or postFilters instead.

​
Matching

Values are matched exactly and case-sensitively. "Featured" and "featured" are different values, and a value that matches nothing simply has no effect — no error is returned.
valueBoost does not use the field-name object shape that filters, notFilters, and postFilters share. It is an array of { fieldName, boosts } entries. Sending the object form returns 200 with the parameter ignored.
valueBoost is also accepted on AI Chat, where it shapes the documents used to ground the answer. It is not accepted on AI Summary, which summarises sources you supply — apply the boost to the Search request that produces those sources instead.

​
Pagination

TotalDocument in the response gives the total number of matching documents — use it together with perPage to compute how many pages exist. If you need result counts higher than the deep-pagination cap, narrow the query with filters instead of paginating further.

Authorizations

​
Authorization
string
header
required

SiteKey authentication. Pass the full value including the SiteKey prefix: SiteKey <base64(customerId:engineId:searchKey)>. Example: SiteKey dGVzdDoxMjM0NTY3Ojk4NzY1. See the Authentication guide for details.

Path Parameters

​
customerId
integer
required

Your Cludo account ID. Find it in MyCludo.

​
engineId
integer
required

The search engine to query. Must match the engine ID in your SiteKey.

Body

application/json
​
query
string
required

Search text. Use * with operator: OR for match-all. Maximum 300 characters; longer queries are rejected with a 400 error.

Example:

"*"

​
page
integer

Page to retrieve, starting at 1.

Required range: x >= 1
Example:

1

​
perPage
integer

Results per page.

Required range: x >= 1
Example:

10

​
filters
object

Include filter. Each key is an indexed field name mapped to allowed values ({"Category": ["Analytics"]}). The reserved keys range, date, and geo_distance express numeric, date, and geo-distance filters — see Filter value formats.

​
notFilters
object

Exclude filter: same grammar as filters (value / range / date / geo_distance). Removes matching documents.

​
postFilters
object

Post-filter: same field-name → values shape as filters (value / range / date / geo_distance — see Filter value formats). Unlike filters/notFilters (which run with the query and shape both ranking and facet counts), post-filters are applied after the query — they narrow the documents returned without changing the Facets counts. This is what powers faceted navigation: ticking one facet value filters the results while the other facet counts stay intact. Set enableFacetFiltering: true to also apply them to the returned facets. Cannot be combined with advancedPostFilter.

​
postFiltersOperator
enum<string>

How multiple post-filter fields combine: AND (default) requires every field to match; OR requires any one.

Available options:
AND,
OR
Example:

"AND"

​
sort
object

Sort by field. Value: Ascending or Descending. Multiple entries apply secondary sorts in order.

​
responseType
enum<string>

JsonObject — structured TypedDocuments (recommended). JsonHtml — pre-rendered HTML fragments.

Available options:
JsonObject,
JsonHtml
​
fields
string[]

Limits which fields are returned on each hit. Only the fields listed here will appear in TypedDocument.Fields — all others are omitted from the response.

​
highlight
boolean

Wrap matching terms in <b>…</b> via each field's Highlights array.

​
enableFacetFiltering
boolean

When true, the request's postFilters (or advancedPostFilter) are also applied to the returned facet counts, so counts reflect the post-filtered result set. When false (default), facets show the full pre-post-filter distribution. This flag does not control whether facets are returned — that is driven by the engine's configured facet fields.

​
rangeFacets
object

Count documents in date or numeric ranges. Each key becomes a label in the RangeFacets response with an array of counts per range. Example: {"This year": {"fieldName": "Date_date", "ranges": [{"from": "2024-01-01", "to": "2024-12-31"}]}}.

​
valueBoost
object[]

Promote documents whose field matches specific values, for this request only. Applies on top of the boosting rules configured on the engine. Note this is an array, not a field-name object like filters.

​
operator
enum<string>

OR — any term matches (broader). AND — all terms required (narrower).

Available options:
AND,
OR
Example:

"OR"

​
enableRelatedSearches
boolean

Populate RelatedSearchDocuments with suggested follow-up queries.

Example:

false

​
enableHybridSearch
boolean

AI Search ranking is enabled by default on AI-enabled engines. Set to false to opt out and use keyword-only ranking for this request.

Response

Search results returned successfully.

​
TypedDocuments
object[]

Ranked hits for the current page (at most perPage items).

​
TotalDocument
integer

Total matching documents across all pages.

​
Facets
object

Per-field aggregation buckets for the engine's configured facet fields. enableFacetFiltering controls whether postFilters constrain these counts — not whether the object is present.

​
RangeFacets
object

Document counts for each range bucket defined in the request's rangeFacets.

​
Banners
object[]

Promotional banners triggered by this query.

​
Suggestions
string[]

Spell-correction / "did you mean" strings.

​
Synonyms
string[]

Synonym terms applied for this query.

​
RelatedSearchDocuments
string[]

Suggested follow-up queries (when enableRelatedSearches is true).

​
FixedQuery
string | null

Spell-corrected query string used for retrieval, or null if unchanged.

​
ResponseTime
integer

Server-side processing time in milliseconds.

​
QueryId
string

ID for this search — pass to tracking and AI endpoints.

​
GenerativeAnswerAvailable
boolean

Whether AI Chat can answer this query.