Skip to main content
POST
/
api
/
v4
/
{customerId}
/
{engineId}
/
search
Execute Search
curl --request POST \
  --url https://api.cludo.com/api/v4/{customerId}/{engineId}/search \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "*",
  "page": 1,
  "perPage": 10,
  "filters": {},
  "notFilters": {},
  "sort": {},
  "fields": [
    "<string>"
  ],
  "highlight": true,
  "enableFacetFiltering": true,
  "rangeFacets": {},
  "valueBoost": {},
  "operator": "OR",
  "enableRelatedSearches": false,
  "enableHybridSearch": true
}
'
{
  "TypedDocuments": [
    {
      "ResultIndex": 1,
      "Score": 12.84,
      "TitleHasHighlight": true,
      "Fields": {
        "Title": {
          "Field": "Title",
          "Value": "Search API overview",
          "Values": [
            "Search API overview"
          ],
          "Highlights": [
            "<b>Search</b> API overview"
          ],
          "IsArray": false
        },
        "Url": {
          "Field": "Url",
          "Value": "https://docs.example.com/search-api",
          "Values": [
            "https://docs.example.com/search-api"
          ],
          "Highlights": [],
          "IsArray": false
        }
      }
    }
  ],
  "TotalDocument": 847,
  "Facets": {
    "Category": {
      "FieldName": "Category",
      "Field": "Category",
      "MissingCount": 14,
      "AllCount": 847,
      "Items": [
        {
          "Key": "Documentation",
          "Count": 412
        },
        {
          "Key": "Tutorial",
          "Count": 235
        }
      ]
    }
  },
  "RangeFacets": {
    "This year": [
      42
    ]
  },
  "Banners": [
    {
      "id": 1001,
      "name": "Featured promotion",
      "websiteid": 12345
    }
  ],
  "Suggestions": [
    "search api",
    "search setup"
  ],
  "Synonyms": [
    "query",
    "lookup"
  ],
  "RelatedSearchDocuments": [
    "getting started",
    "api authentication"
  ],
  "FixedQuery": "",
  "ResponseTime": 96,
  "QueryId": "a3f2c1b8-4e9d-4a1c-9b2e-7f4d6e8a1c3d",
  "GenerativeAnswerAvailable": true
}
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.

​
Pagination

FieldTypeNotes
pageinteger1-indexed. The first page is page: 1.
perPageintegerNumber of results per page.
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.

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: field name → allowed values. Example: {"Category": ["Analytics"]}.

​
notFilters
object

Exclude filter: same shape as filters. Removes matching documents.

​
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

Return a Facets object with per-field value counts for filter UIs.

​
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

Boost relevance for documents matching these field values. Example: {"Category": ["Featured"]}.

​
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. Present when enableFacetFiltering is true.

​
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.