Search
Search API
The search widget calls this endpoint for you, so most integrations never touch it directly. It is documented because it is a public contract: you can call it from your own front end, from a server, or from a mobile app, and it behaves the same way.
The endpoint is public and is called directly from the visitor's browser, the same way the widget calls it. No API key or server-side code is required.
Endpoint
GET https://search.cognito.cz/api/search
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | yes | UUID of your search instance. |
q | string | no | The search query. Omit it (or send an empty value) to get the most popular items. |
lang | string | no | Content language of the results. See Content language below. |
categories | string | no | Comma-separated category facet values to filter by, as returned in facets.categories. |
limit | integer | no | Maximum results per source. |
Find instanceId under Instances → Embed widget in the admin panel.
Your site's origin must be on the instance's domain allowlist (Instance → Domains), exactly as for the search widget.
Example request
GET https://search.cognito.cz/api/search?instanceId=11111111-1111-1111-1111-111111111111&q=ibalgin&lang=de
Content language
A search instance declares the set of content languages it serves and one of
them as its default (Instance → Content languages). lang selects which
of those languages the results come from — see
Multi-language feeds for how the
languages get into your index in the first place.
Resolution is deliberately forgiving:
lang | Result |
|---|---|
| One of the instance's declared languages | Results in that language |
| A valid code the instance does not declare | Results in the instance's default |
| An unknown or malformed value | Results in the instance's default |
| Omitted | Results in the instance's default |
No value of lang produces an error. The widget runs on pages we do not
control, and a typo in an embed snippet must fall back to your default
language rather than break search on your site. If you need to know which
language you actually got, send a language you have declared.
Case and surrounding whitespace do not matter — DE, de and %20de%20 all
resolve to the same language.
A language you have declared but never indexed returns no results rather than an error — the same shape as a query that simply matched nothing.
Content language and interface language are separate
lang on the search API is only about the content. The widget's lang
option sets both: the language of the results and the language of the
widget's own labels (which currently exist in Czech and English, falling back
to English). That is intentional — a German storefront can show German
products with English widget chrome, and a Czech-speaking administrator can
inspect a German catalog.
Switching language
Every request carries its own lang, so there is no session or state to
change — send the new value on the next request and re-render.
If you use the widget rather than calling this endpoint yourself, and your
language switcher does not reload the page, call
SearchWidget.setLanguage('de'). See
Multi-language feeds for the whole
picture, from feed to query.
Category facets
facets.categories in the response holds the category values for the
language you searched in, because category paths are part of your translated
content. They are therefore not interchangeable between languages: if you
build your own filtering UI, drop any active categories filter when you
change lang, then re-query — filtering German results by a Czech category
path matches nothing. The widget does this for you.