Search
Search
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Query a site's index and power autocomplete. Search endpoints require a search
key (?key=sk_… or the X-Search-Key header) and work only on the
site's own domain.
Each successful search counts against the plan's monthly quota.
Base URL: https://searcio.com/api/v1/sites/{site}, or key-relative
https://searcio.com/api/v1, where the site is resolved from the search
key.
GET /search
Run a full search, with typo tolerance, type filtering, facets and highlighting.
Query parameters
| Param | Type | Default | Notes |
|---|---|---|---|
q |
string (≤ 255) | None | The search terms. When omitted or empty, every document matches, which is useful for browsing a type. A last word of three or more letters also matches as the start of a longer word, so Briefkas already finds "Briefkasten" while the visitor is typing. |
type |
string (≤ 255) | None | Restrict to one or more content types, separated by commas (product,post). |
filter[field] |
string (≤ 255) | None | Exact match on a configured facet field. Values separated by commas are combined with OR (filter[color]=red,blue), unless the field's facet_match is all, in which case a result must carry every value. For values that contain a comma themselves (category names such as "Jacken, Mäntel & Strick"), send the list form instead, one whole value per entry: filter[categories][]=Jacken, Mäntel & Strick&filter[categories][]=Herrenmode (at most 50 entries of 255 characters). Different fields always combine with AND. filter[lang] is always allowed. |
range[field] |
string (≤ 64) | None | Numeric range on a configured facet field, as min:max, with either side optional: range[price]=:100 (≤ 100), range[price]=50: (≥ 50), range[price]=50:100. |
keywords |
string (≤ 255), or a list of up to 10 | None | Words that every result's name (or SKU) must contain; the description is not searched. Alternatives are separated by commas, and one of them must match (keywords=Panzerriegel,Zusatzschloss). An alternative of several words needs all of them, and its last word also matches the start of a longer word (Fenster finds "Fenstergitter"). Send keywords[]=… several times to require several groups at once. Unlike q, it does not affect ranking, trigger redirects or count as a search term: it only narrows the results, the way a quiz answer does. |
page |
int ≥ 1 | 1 |
Page number, starting at 1. |
per_page |
int, 1 to 100 | 20 |
Results per page. |
sort |
string | None | An order instead of relevance: newest (by the documents' published_at, newest first), price_asc or price_desc. Documents sent with in_stock: false still come last, and documents without the field come after those that have it. A sorted search always matches by keywords, also on a site with AI search, and leaves out personalized and profit ranking and merchandising pins (what a rule hides stays hidden). Most useful with an empty q, for a "new in" row. |
key |
string | None | The search key (or send X-Search-Key). |
live |
boolean | false |
Set on requests sent while the visitor is still typing. They are kept out of the site's search counts unless a result from them is clicked. Send the final search (on Enter, or when a suggestion is picked) as its own request without live. |
origin |
string | None | How the visitor started the search: typed, suggestion, popular, recent, voice or filter. Analytics only. |
surface |
string | None | Where the results are shown: overlay, highlights, category or quiz. Analytics only; most useful on listings with an empty q. |
preview |
boolean | false |
Set from a page builder's editor preview. The request is still metered, but not recorded in the site's analytics. |
highlight |
boolean | true |
Set to false when you do not show the highlight snippets. Highlighting is the most expensive part of a search, so leaving it out makes every search noticeably faster. Each hit's highlight is then null. |
origin, surface and preview only feed analytics and never change the
results. live also keeps typing fast on a site with AI search: such requests
rank by meaning only when the same words were searched before, and by keywords
otherwise, while the final search always ranks by meaning. An unknown origin
or surface value is ignored, not rejected.
Filterable fields must first be declared as facet fields, either in the
Searcio dashboard under Search settings or through the
search configuration endpoint. Filtering on any other field
returns 422. A curated "featured" carousel needs nothing more than a filter:
send a featured field with your documents and query filter[featured]=true.
What shapes the results
The same request can rank differently from site to site: matching and ordering are driven by the site's own search settings, not by this endpoint. In effect:
- Searchable fields and weights decide what
qmatches and how strongly. - Synonyms expand the
query, so
trainerscan match a product that only sayssneakers. - Type boosts lift whole content types (for example, products above posts).
- AI search, when enabled, blends in semantic matching, so results match on meaning and not only on words.
- Merchandising
pins and hides products, and can attach a
bannerto a query. - Personalized ranking, when enabled, lifts the results visitors click most for that query.
None of this changes the shape of the response, only which documents come back and in what order, so an integration written against this contract keeps working while the site owner tunes their search. The one exception is a matching search redirect, which replaces the whole response.
Redirects
A search term that exactly matches a configured search redirect (ignoring case and surrounding spaces) ends the request early: no search runs, the request does not count against the plan's search quota, and it is not recorded in search analytics. The response has a different shape from a normal search:
{ "query": "black friday", "redirect": "https://example.com/black-friday" }Check for a redirect key before rendering a results list; when present,
navigate the visitor there instead.
Example
curl "https://searcio.com/api/v1/sites/123/search?q=runing%20sho&type=product&per_page=10&key=sk_live_xyz"Response 200 OK
{
"query": "runing sho",
"search_id": "9f1c2b7e-5f3a-4a1e-9d64-2f0c1b3a8e77",
"total": 12,
"total_exact": true,
"page": 1,
"per_page": 10,
"hits": [
{
"id": "p-1",
"score": 7.84,
"source": {
"title": "Red Running Shoes",
"type": "product",
"url": "/products/red-shoes",
"price": 89.9,
"image": "https://cdn.example.com/red.jpg"
},
"highlight": { "title": ["Red <em>Running</em> <em>Shoes</em>"] }
}
],
"facets": {
"types": [
{ "value": "product", "count": 10 },
{ "value": "post", "count": 2 }
],
"brand": [
{ "value": "Acme", "count": 7 },
{ "value": "Duff", "count": 5 }
]
}
}Response fields
| Field | Meaning |
|---|---|
total |
Total matching documents, across all pages. |
total_exact |
true when total and the facet counts count every match. false when the search ranked by meaning (AI search): the counts then cover the results it retrieved, which is less than every match, so show them as an estimate or not at all. |
search_id |
Identifies this search. Send it back to POST /search/click when a visitor opens a result, so clicks can be attributed to the search that produced them. |
hits[].id |
Your document id. |
hits[].score |
Relevance score (higher is better). |
hits[].source |
The stored document fields. |
hits[].highlight |
Snippets per field with <em> around matches (may be null). |
hits[].pinned |
Present and true only on a product pinned to the top by a merchandising rule. |
facets.types |
Counts per content type, to render as filters. |
facets.<field> |
Counts for each configured facet field, to render as filter chips that search again with filter[<field>]=. |
facets.<field>_paths |
For a category tree, each value also has label (the last level, the name to show) and parent (the path one level up, null at the top): { "value": "Fahrwerke > Gewindefahrwerke", "label": "Gewindefahrwerke", "parent": "Fahrwerke", "count": 3723 }. Every value of the field is returned, not only the fifty most frequent. |
banner |
A promotional banner string when a merchandising rule matches the search, otherwise null. |
How matching works
- Typo tolerance:
runingstill findsrunning. A word that holds a digit, such as an article number or1001, must match exactly. - Codes and article numbers: a search in which every part holds a digit
(
FAQWORT-1001,5520) is answered by the words alone, also on a site with AI search, so a code that is not in the catalogue finds nothing instead of loosely related products. Every part of the code must be there:FAQWORT-1001does not find theAW-1001that shares its number, whileAW-10still findsAW-1001as you type.Größe 42and4k tvstill have a word in them and search as usual. - Accents and case are ignored:
cafematchesCafé. - Compound words: in languages that join words (German, Dutch, the
Scandinavian languages, Finnish), a word of four letters or more is also
found inside a longer word of the title, so
schlossfinds "Türschloss" andwollefinds "Merinowolle". Such a match counts as much as the title's weight: it ranks below a title that holds the word itself and above a document that only has the word in its text. It applies to a search in one of these languages, to a site whoselanguagesinclude one, and to a site that names no language, and only whentitleis one of the searched fields. - Field weights and boosts: the site's search settings control which fields are searched, their weights, and boosts per content type.
- Stock ranking: a product sent with
in_stock: falsestill appears in the results and in the total count, but ranks below every other result. A search of two words or more that a sold-out product's name contains as a phrase keeps that product in its place, since the visitor is looking for it.
Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
402 |
The account has no active plan (reason: no_active_plan) or an overdue payment (reason: payment_overdue). Applies to every endpoint that takes the search key. |
403 |
Site disabled, Origin not the site's own domain, or the account is suspended (reason: account_suspended) |
422 |
Invalid parameters (for example per_page > 100, or filter[...] on a field that is not a facet) |
429 |
Monthly search quota reached ({ "metric": "searches", "limit": N }) or rate limited |
GET /storefront-config
What this site's plan and setup allow, so a storefront can decide what to render before it draws anything. Authenticated with the search key, so it is safe to call from the browser.
A widget should never offer an AI chat tab that can only answer 403. Read
capabilities.assistant and show or hide the tab accordingly. When the account
upgrades, the flag changes on its own, with no change to the storefront.
Request
GET /api/v1/sites/123/storefront-config?key=sk_live_abcResponse 200 OK
{
"capabilities": {
"assistant": true,
"semantic_search": true,
"visual_search": false,
"quiz": true
},
"facets": ["brand", "color"],
"languages": ["en", "de"]
}| Field | Meaning |
|---|---|
capabilities.assistant |
The AI shopping assistant is available to this site. Render the AI chat tab only when true. |
capabilities.semantic_search |
Searches are answered by meaning, not only by keywords. |
capabilities.visual_search |
The site has visual search turned on. Render the photo upload button only when true. |
capabilities.quiz |
The site has at least one published quiz. Render the quiz entry point only when true. |
facets |
Facet fields you may render as filters (the same ones filter[...] accepts). |
languages |
Languages this site serves. |
Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
403 |
Site disabled, or Origin not the site's own domain |
POST /search/click
Records that a visitor opened a result. Clicks power the click-through rate in the site's analytics, the clearest signal of whether results are actually relevant. Reporting them is optional but strongly recommended: without clicks, a site can see what people search for but not whether they found it.
Clicks also feed personalized ranking: when a site turns it on, the results people click most for a query are lifted for everyone who runs it. Reporting clicks is therefore what makes ranking improve over time; a site that never sends them keeps pure relevance order.
Authenticated with the search key, like /search itself, so it can be
called straight from the browser. It queues the write and returns immediately,
so send it as a beacon and never make the visitor's navigation wait for it.
Request
POST /api/v1/sites/123/search/click?key=sk_live_abc
Content-Type: application/json
{
"search_id": "9f1c2b7e-5f3a-4a1e-9d64-2f0c1b3a8e77",
"document_id": "p-1",
"position": 3
}| Field | Required | Meaning |
|---|---|---|
search_id |
yes | The search_id from the search response the visitor clicked through from. |
document_id |
yes | The id of the clicked document (your id, as sent when indexing). |
position |
yes | The result's position in the list the visitor saw, starting at 1. |
Response 202 Accepted
{ "recorded": true }Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
403 |
Site disabled, or Origin not the site's own domain |
422 |
Invalid payload (bad uuid, missing id, position < 1) |
Wiring it up
// Keep the search_id from the last search response…
const { search_id, hits } = await search(query);
// …and report the click, without delaying the navigation.
function onResultClick(hit, index) {
navigator.sendBeacon(
`${base}/sites/${siteId}/search/click?key=${searchKey}`,
new Blob([JSON.stringify({
search_id,
document_id: hit.id,
position: index + 1,
})], { type: 'application/json' }),
);
}Privacy. A click stores only the search id, your document id and the position. Like the search log itself, it holds no visitor identifier. Clicks are deleted after the same retention period as recorded searches. Personalized ranking reads them only in aggregate (clicks per document per term), so it never builds a profile of a visitor.
GET /search/suggest
Lightweight autocomplete for a search box that suggests as the visitor types. Returns distinct title suggestions, matching on prefixes.
Query parameters
| Param | Type | Default | Notes |
|---|---|---|---|
q |
string (≤ 255) | None | Required. The partial query. |
limit |
int, 1 to 20 | 5 |
Maximum number of suggestions. |
type |
string (≤ 255) | None | Suggest only from these content types, separated by commas, as on /search. Send the same type as the search the field runs, so a field for guides suggests guide titles. |
filter[field] |
string (≤ 255) | None | The same filters as /search, in the comma or the list form: a configured facet field or lang. Send the page's filter[lang] so a German page suggests German titles; a document without lang is suggested in every language. |
key |
string | None | The search key (or X-Search-Key). |
Example
curl "https://searcio.com/api/v1/sites/123/search/suggest?q=sho&limit=5&filter[lang]=de&key=sk_live_xyz"Response 200 OK
{ "suggestions": ["Red Running Shoes", "Blue Trail Shoes", "Shopping Bag"] }Suggestions come from prefix matching on title (an edge n-gram analyzer), so
they update with every character typed. Further fields, such as sku, can be
added through suggest_fields in the search configuration;
typing a product number then suggests the product's title. Suggest calls are
intentionally cheap and are not metered as searches.
GET /search/popular
The most popular searches on this site over the last 30 days, for a "Popular searches" list shown in a search modal before the visitor types.
Query parameters
| Param | Type | Default | Notes |
|---|---|---|---|
limit |
int, 1 to 20 | 10 |
Maximum number of searches. |
filter[lang] |
string | None | The page's language on a multilingual shop: only terms searched on pages in that language. Searches recorded before the language was kept carry none, so a language's list fills up as new searches come in. Without it, every term is listed. |
key |
string | None | The search key (or X-Search-Key). |
Example
curl "https://searcio.com/api/v1/sites/123/search/popular?limit=10&key=sk_live_xyz"Response 200 OK
{
"popular": [
{ "query": "wein", "count": 1240 },
{ "query": "bier", "count": 980 }
]
}- Cached for 15 minutes and not metered as a search.
- Searches that returned no results are excluded, and a search must have been run more than once before it appears, so a single visitor's unique query is never exposed.
- Terms the merchant hid (
excluded_popular_termsin the search configuration, or in the Searcio dashboard) never appear; the list fills up with the next terms instead. A change to that list takes effect at once, not after the cache.
GET /search/similar
More like this: products similar to a given one, for a "You may also like" or related products carousel. Similarity is semantic: it uses the source product's own AI embedding to find its nearest neighbours, then excludes the product itself.
Only available on sites with AI search enabled. On other sites it returns an empty list, never an error, so a recommendations widget degrades gracefully. It is not metered as a search.
Query parameters
| Param | Type | Default | Notes |
|---|---|---|---|
id |
string (≤255) | None | The source product's document id. Required. |
limit |
int, 1 to 20 | 6 |
How many similar products to return. |
type |
string (≤ 255) | None | Only documents of these content types, separated by commas (type=product). Without it, the row may also hold posts and guides that write about the product. |
filter[lang] |
string | the product's own | The language of the similar products. Without it, they keep to the source product's lang (otherwise a product's nearest neighbour is its own translation); documents without a language always qualify. Only lang is accepted here. |
key |
string | None | The search key (or X-Search-Key). |
preview |
boolean | false |
Set from a page builder's editor preview, so the list is not recorded in the site's analytics. |
Example
curl "https://searcio.com/api/v1/sites/123/search/similar?id=p-1&limit=4&key=sk_live_xyz"Response 200 OK
{
"search_id": "2b7e9f1c-3a4a-4e1e-8d64-0c1b2f3a8e77",
"similar": [
{ "id": "p-2", "score": 0.94, "source": { "title": "Blue silk dress", "price": 79.9 } }
]
}Each entry has the same source shape as a search hit; the embedding vector is
never included. Send search_id to /search/click when a
visitor opens one of the products, so the site's analytics can tell how often
recommendations are followed. The empty list returned without AI search has no
search_id.
POST /assistant
The conversational shopping assistant. A shopper describes what they want in
natural language ("a warm waterproof jacket under €100 for a woman"); the
assistant works out the intent and constraints, searches this site's
catalogue only, and replies with a recommendation and the matching products
to render. It is a premium feature, available on plans that include AI search;
check capabilities.assistant in /storefront-config
before offering it.
The endpoint is stateless: to continue a conversation (to refine, or to
"compare the best options"), send the recent turns back in history.
Request
curl -X POST "https://searcio.com/api/v1/sites/123/assistant?key=sk_live_xyz" \
-H "Content-Type: application/json" \
-d '{
"message": "a warm waterproof jacket under 100 euros",
"history": [
{ "role": "user", "content": "…previous message…" },
{ "role": "assistant", "content": "…previous reply…" }
]
}'| Field | Type | Notes |
|---|---|---|
message |
string (≤ 2000) | The shopper's message. Required. |
history |
array (≤ 20) | Earlier turns, for context. Each is { role, content }, with role either user or assistant and content ≤ 4000. Optional. |
filter[lang] |
string | Optional. The page's language on a multilingual shop: every product search the assistant runs keeps to it (documents without a language still qualify). The reply is written in the shopper's own language, and in this one when a message is too short to tell. |
Response 200 OK
{
"reply": "For sightseeing you'll want something windproof and light. Here are a few under €100…",
"products": [
{ "id": "p-1", "source": { "title": "Pure Snow Shell", "price": 95.99, "image": "https://…" }, "search_id": "7d3e…" }
]
}products are the catalogue items the assistant found in this turn, with the
same source shape as a search hit, ready to render as a result grid. Each
carries the search_id of the catalogue search that found it; send it to
/search/click when the shopper opens the product.
On a site that indexes products alongside other content, the assistant searches
products only. When the shopper asks for advice, tips or guides, it searches the
other content instead, and products then holds those documents, recognisable
by their type (such as post). Render each item by its type, as you would a
search hit.
Errors
| Status | Meaning |
|---|---|
403 |
The account's plan does not include AI search, or the assistant is not available. |
422 |
The message failed validation or was blocked by a safety guardrail. |
429 |
The account's AI usage limit has been reached (see Errors & rate limits). |
502 |
The AI provider was momentarily unavailable. Retry, or fall back to /search. |
The endpoint has a strict rate limit, and every reply uses one of the plan's
monthly AI messages, the same allowance the
account owner sees on their dashboard. Check
/storefront-config before rendering a chat interface,
so you never offer a tab the plan cannot use. Shopper messages are treated
strictly as data and screened for prompt injection, and the assistant only ever
talks about real catalogue products.
POST /assistant/stream
The same turn as POST /assistant, sent as
server-sent events while it happens: the products as soon as the
assistant's search finds them, then the reply word by word. The shopper sees
the products a few seconds before a plain reply would arrive, and the text
starts right after.
It takes the same body, the same filter[lang], the same rate limit and the
same checks, and it uses one monthly AI message in the same way. Everything that
can be refused is refused before the stream opens, as a normal JSON error
with the status codes of POST /assistant: 403, 422 for
validation or a blocked message, 429, and 502 when the provider cannot be
reached. A 200 response is text/event-stream.
curl -N -X POST "https://searcio.com/api/v1/sites/123/assistant/stream?key=sk_live_xyz" \
-H "Content-Type: application/json" \
-d '{ "message": "a warm waterproof jacket under 100 euros", "filter": { "lang": "en" } }'event: products
data: {"products":[{"id":"p-1","source":{"title":"Pure Snow Shell","price":95.99},"search_id":"7d3e…"}]}
event: delta
data: {"text":"For sightseeing"}
event: delta
data: {"text":" you'll want something windproof"}
event: done
data: {"reply":"For sightseeing you'll want something windproof…","products":[…]}| Event | Data | What to do |
|---|---|---|
products |
{ products } |
Render the grid. It can arrive again in the same turn, after a second search, with the full list so far: replace the list, don't append to it. |
delta |
{ text } |
Append to the reply bubble. |
done |
{ reply, products } |
The turn is complete. reply is the whole text, the same as the deltas joined; keep it in history for the next turn. products is the final list. |
error |
{ error } |
The turn failed partway; show the message. Nothing was metered. |
Each event is one event: line and one data: line holding JSON. An
EventSource cannot send a POST body, so read the response with fetch() and
a stream reader, splitting on blank lines. If the shopper closes the chat in
the middle of a reply, the turn still finishes on the server and is counted
once.
Frontend integration tips
flowchart LR
Box["Search box"] -- "on keypress (debounced)" --> Sug["/search/suggest"]
Box -- "on submit / Enter" --> Sr["/search"]
Sr --> Results["Results list + facets"]
Sug --> Drop["Suggestions dropdown"]- Debounce suggest calls (about 150 to 250 ms) to avoid a request per keystroke.
- From the browser, pass the key as the
keyquery parameter (not the header) to avoid CORS preflight requests. - Render
facets.typesas filter chips; clicking one searches again withtype=. - Show
highlightwhen present; it makes relevance obvious to the visitor. If your results do not show the snippets, sendhighlight=false: the search is then noticeably faster. - Open the connection early: a
<link rel="preconnect">to the API's origin in your storefront's<head>takes the connection setup out of the first search. - Degrade gracefully: if a request fails, fall back to your platform's native search.