Search
Search configuration
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Read and update a site's search configuration with the server-side write credentials, so a plugin can manage searchable fields, weights, boosts, facets and languages from its own settings screen without sending the user to the Searcio dashboard.
Base: https://searcio.com/api/v1/sites/{site}, or key-relative
https://searcio.com/api/v1 (the site is resolved from the write key).
Auth: X-Write-Key and X-Write-Secret headers (see
Authentication & security).
GET /search-config
Returns the effective configuration: defaults are filled in for anything the site has not configured yet.
curl "https://searcio.com/api/v1/search-config" \
-H "X-Write-Key: $WK" -H "X-Write-Secret: $WS"Response: 200 OK
{
"searchable_fields": [
{ "field": "title", "weight": 5 },
{ "field": "content", "weight": 1 },
{ "field": "sku", "weight": 4 }
],
"type_boosts": [
{ "type": "product", "boost": 2.0 }
],
"facet_fields": ["brand", "color", "features", "weight"],
"facet_match": { "features": "all" },
"numeric_fields": ["weight"],
"field_labels": { "attr_farbe": "Farbe" },
"suggest_fields": ["title", "sku"],
"synonyms": ["sneaker, trainer"],
"languages": ["de", "en"],
"currency": "EUR",
"excluded_popular_terms": ["test"],
"merchandising": [
{
"query": "winter",
"match": "contains",
"filter_field": null,
"filter_value": null,
"lang": null,
"pinned": ["p-100", "p-205"],
"hidden": ["p-999"],
"banner": "Winter sale: up to 40% off"
}
],
"redirects": [
{ "query": "black friday", "url": "https://example.com/black-friday", "lang": null }
],
"profit_ranking": {
"enabled": false,
"strength": 15,
"target": 25,
"min_profit": null,
"rules": [],
"excluded_terms": [],
"listings": true
},
"features": {
"ai_search": { "available": true, "enabled": true, "status": "ready" },
"visual_tagging": { "available": true, "enabled": false },
"visual_search": { "available": true, "enabled": false },
"personalization":{ "available": true, "enabled": true }
}
}| Key | Meaning |
|---|---|
searchable_fields |
Which fields full-text search matches, and their relative weight (1 to 100). |
type_boosts |
Ranking boosts per content type (0.1 to 100). |
facet_fields |
Fields returned as facets on /search and allowed in filter[...]. |
facet_match |
How several values picked for one facet field combine, per field: "any" (OR, the default) or "all" (AND: a result must carry every value), for example { "features": "all" }. A field that is not listed is "any"; a key that is not a facet field is dropped on save. Always an object ({} when nothing is set). The same choice is available in the Searcio dashboard, next to each facet field. |
numeric_fields |
Your own fields that hold numbers (up to 20), mapped as numbers, so range[...] on them compares numbers rather than text ("10" after "9") and their facet values are numbers. price, price_min, price_max, regular_price, sale_price and rating are numbers already; fields Searcio maps itself (title, type, url and the like) cannot be listed. A value that is not a number, such as "5 min", is left out of the field without refusing the document. Changing the list rebuilds the site's index in the background; search keeps answering from the old index until the new one holds every document. |
variant_fields |
Filter fields that a product's variants carry (up to 20), such as attr_color and attr_size. Filters on them must all be met by one variant that is not sold out: red and XL find a jacket only when one of its variants is both and in stock. A product sent without variants is filtered by its own fields. Setting the first field rebuilds the site's index in the background, so the variants can be searched one by one. |
field_labels |
What the shop calls its fields, by field name, for the Searcio dashboard to show instead of the name: { "attr_farbe": "Farbe", "attr_groesse": "Größe" } (up to 100 fields, each label up to 100 characters). Write the labels in the shop's own language. Sent whole like the other lists, so a field left out has no label of its own; a blank label is dropped; a key that is not a field name, or a private field such as cost_price, is refused. Always an object ({} when nothing is set). The dashboard uses them where it lists a site's fields, such as the field menu of the profit ranking rules and the quiz builder. |
suggest_fields |
Fields queried by /search/suggest (defaults to title). |
synonyms |
Comma-separated synonym groups, one string per group. |
languages |
Languages the site indexes (empty means unrestricted). Use the same codes as on your documents; see Languages & currencies. |
excluded_popular_terms |
Searches never offered as popular searches, such as test searches (at most 200, of up to 255 characters each). Each entry hides exactly that term, regardless of capitalisation; entries are trimmed, and duplicates and empty entries are dropped. Also editable in the Searcio dashboard. Always a list ([] when nothing is set). |
currency |
The shop's currency as an ISO 4217 code (EUR), or null when it has not been reported. The shopping assistant writes prices in it, and so do result cards whose price is set to the shop's currency; without it the model has to guess, and tends to guess dollars. Send it whenever the settings are saved and on the daily sync; null clears it. For the accepted codes, see Languages & currencies. |
merchandising |
Curation rules, in order. See Merchandising rules. |
redirects |
Search term redirects, in order. See Search redirects. |
profit_ranking |
Lifting products whose margin reaches a target. See Profit ranking. |
features |
Site-level capabilities. See Feature switches. |
Merchandising rules
A rule curates the results of chosen searches, of a category listing page, or both: it forces products to the top, keeps products out, and can return a banner for your storefront to show above the results.
{
"query": "winter",
"match": "contains",
"filter_field": null,
"filter_value": null,
"lang": null,
"pinned": ["p-100", "p-205"],
"hidden": ["p-999"],
"banner": "Winter sale: up to 40% off"
}| Field | Meaning |
|---|---|
query |
The search trigger, matched against the search term. An empty string applies the rule to every search, which is the intended way to hide a product everywhere. |
match |
How query is compared with the search term, ignoring capitalisation. "contains" (the default) fires whenever the term contains the trigger, also inside a longer word, so "jacke" fires on "regenjacke". "exact" fires only when the term is the trigger itself, so "kopfhörer" does not fire on "kopfhörerverstärker". Omitted or null means "contains". |
filter_field / filter_value |
Optional category trigger: the rule fires when this facet filter is active with this value (for example on a category listing page). Combine it with query to require both, or set it alone to fire on every visit to that filter value, whatever the search term. |
lang |
Optional language code (de, en). The rule then fires only on a request whose filter[lang] names that language. null fires in every language. A request without filter[lang] matches the rule only when the site has at most one language in languages. Use it on a multilingual shop, where a German trigger such as "jacke" is also contained in the English "jacket". |
pinned |
Document ids forced to the top, in the order given. A pinned product only appears when it matches the request's own filters, ranges and language, so narrowing the results never brings an excluded product back to the top. A search that asks for a sort leaves pins out: the visitor's order wins, while what a rule hides stays hidden. |
hidden |
Document ids removed from the results entirely. |
banner |
Optional message returned with the results, or null. |
Every rule that matches a request applies, and they are combined in the order
of the list: a product any of them hides is hidden, the pinned products of an
earlier rule come before those of a later one, and the banner is the first
matching rule's that has one. A rule with an empty query therefore hides a
product in every search, whatever other rules the search fires.
Limits: at most 50 rules, 50 ids per list, 255 characters per id and 2000 per banner. A rule with no query, no category trigger, no pins, no hidden products and no banner would have no effect, so it is dropped rather than stored.
Rules written here are the same rules the Searcio dashboard edits, so the two always agree.
Search redirects
A redirect sends a visitor straight to a URL instead of running a search. Use it for well-known lookups that should skip the results page entirely, such as a promo code, a support phone number or a page name.
{ "query": "versand", "url": "/versand/", "lang": "de" }| Field | Meaning |
|---|---|
query |
The search term to match exactly (ignoring case and surrounding spaces). Unlike a merchandising trigger, it never matches part of a term. |
url |
The destination. Must start with http://, https:// or / (relative to the site). |
lang |
Optional language code. The redirect then fires only on a search whose filter[lang] names that language, as a merchandising rule's lang does, so "versand" can lead to /versand/ on the German pages and /en/shipping/ on the English ones. null (or no lang) fires in every language. |
Limits: at most 50 rules, 255 characters for query and 2000 for url. A rule
missing either query or url is dropped rather than stored. A matching
redirect is returned from GET /search as
{ "query": "...", "redirect": "..." } instead of a normal results payload, and
does not count against the plan's search quota.
Rules written here are the same rules the Searcio dashboard edits, so the two always agree.
Profit ranking
Lifts products whose margin reaches a target, among the results that match a
search about equally well. Products need a cost_price or margin_percent
(see Document schema).
{
"enabled": true,
"strength": 15,
"target": 25,
"min_profit": 20,
"rules": [
{ "field": "categories", "value": "Televisions", "target": 12, "exclude": false },
{ "field": "brand", "value": "Our own brand", "target": 45, "exclude": false },
{ "field": "categories", "value": "Clearance", "target": null, "exclude": true }
],
"excluded_terms": ["acme", "returns"],
"listings": true
}| Field | Meaning |
|---|---|
enabled |
Whether profit ranking is on. |
strength |
How far a product with a good margin may rise, in percent (1 to 50): at 15, it overtakes only results that match at most 15% better. A much better match always keeps its place. |
target |
The margin in percent from which a product counts as profitable, for every product no rule matches. Below its target a product is not lifted; at the target it gets half the lift, rising evenly to the full lift at twice the target. |
min_profit |
Optional. The least profit per sale, in the shop's currency, a product must earn to be lifted at all, so a cheap product with a high margin stays where it is. null for none. See Margin and profit for the prices it is counted in. |
rules |
Targets of their own for the products carrying a value: a category (categories), a brand or any other field. A category rule also covers its subcategories when documents list a product's categories with their parents. "exclude": true (with "target": null) never lifts those products, for example a clearance category or a brand under a fixed agreement. At most 100. |
excluded_terms |
Search terms ranked by relevance alone, matched whole and whatever their capitals, for example brand names or service terms. At most 200. |
listings |
Optional, true unless set. Whether a listing without a search term, such as a category page or highlights, is ordered by the lift too (see below). Left out of a PUT, it keeps its value. |
When several rules match a product, the more specific one applies: the one whose value fewer products carry. Searcio stores and returns the rules in that order, so the first matching rule is the one that applies.
A rule's value is the value as the products spell it. When you save a value
that differs only in capitals from one the products carry (dunkelblau for
Dunkelblau), Searcio stores the products' spelling.
Margin and profit
The margin is the profit as a share of the price: (price minus cost_price)
divided by price. It is the same with or without tax as long as price and
cost_price are on one basis, both with tax or both without. A shop that sends
margin_percent states that share itself.
The profit per sale, which min_profit is compared with, is price minus
cost_price. When a shop that shows prices with tax also sends the price
without tax (price_excluding_tax, see
Document schema), the profit is
counted without tax, so tax is never mistaken for profit. Without it, the
profit is counted in the prices the shop sends, and the tax counts as profit
when those include it.
Listings without a search term
Without a search term, as on a category page or in highlights, every product
matches equally well, so the lift alone puts them in order, with products out
of stock still last. With "listings": false such a listing keeps its usual
order, while a search with a term is lifted as before. The shopping assistant
recommends in the same order as search. Merchandising pins keep the top
whatever the margins.
Feature switches
features carries four site-level capabilities, so an integration can both
mirror and change what the Searcio dashboard shows.
| Feature | Requires | Effect of enabling |
|---|---|---|
ai_search |
A plan that includes AI search | Queues a full re-index; status changes to pending |
visual_tagging |
A plan that includes AI search | Product images are tagged when they are next indexed |
visual_search |
A plan that includes AI search | Shoppers can search by uploading a photo; see Visual search |
personalization |
Nothing; it works from the click data the site already collects | Takes effect on the next search |
Each feature reports available (the site can turn it on) and enabled (the
site has turned it on). AI search also reports status: pending, indexing,
ready or failed. Read it to show "Index status: Ready" in your own settings
screen.
Writing them
Send only enabled; available and status are reported by the server and
ignored on write.
curl -X PUT "https://searcio.com/api/v1/search-config" \
-H "X-Write-Key: $WK" -H "X-Write-Secret: $WS" \
-H "Content-Type: application/json" \
-d '{ "features": { "ai_search": { "enabled": true } } }'Before you connect this to a checkbox, note:
- Enabling AI search starts a full re-index of the catalogue. Enabling it when it is already on changes nothing and does not queue a second re-index, so a settings form that sends its whole state on every save is safe.
- Disabling is instant and lossless. The existing index keeps serving
keyword results; only the flag and
statusare cleared. - Enabling a feature the plan does not include fails with
422and a field error onfeatures.<name>.enabled, not with403: the rest of your payload is still valid, and the error tells you which field to unset. - Disabling is always allowed, even when the plan no longer includes the feature, so an account that moved to a smaller plan can still switch off what it can no longer use.
PUT /search-config
Replaces the parts of the configuration you send. Keys you omit keep their
current value, so an integration that only manages searchable_fields never
wipes boosts or synonyms configured in the Searcio dashboard. Sending a key
replaces that section entirely, so treat your own settings screen as the source
of truth and send the full section on every save.
curl -X PUT "https://searcio.com/api/v1/search-config" \
-H "X-Write-Key: $WK" -H "X-Write-Secret: $WS" \
-H "Content-Type: application/json" \
-d '{
"searchable_fields": [
{ "field": "title", "weight": 5 },
{ "field": "sku", "weight": 4 }
],
"facet_fields": ["brand"]
}'The response has the same shape as GET and reflects the new effective
configuration. Changes take effect on the very next search, except enabling
features.ai_search, which queues a re-index first (watch
features.ai_search.status).
Validation errors: 422 Unprocessable Entity
Errors name the failing field, so you can show each one next to its input:
{
"message": "The field \"bad field!\" is not a valid field name.",
"errors": {
"searchable_fields.0.field": ["..."]
}
}- Field names must match
[A-Za-z0-9_.-]+. - Weights are integers from 1 to 100; boosts are numbers from 0.1 to 100.
languagesentries are language codes (de,en,pt-BR). The list is rejected with alanguageserror when it exceeds the plan's language limit (see Health for the limit).merchandisingaccepts at most 50 rules, andpinnedandhiddenat most 50 ids each.redirectsaccepts at most 50 rules;urlmust start withhttp://,https://or/.profit_rankingis sent whole:enabled,strength(1 to 50) andtarget(0.1 to 100) are required with it,listingsis a boolean,min_profitis 0 to 1,000,000,rulesholds at most 100 entries (each with atargetof 0.1 to 100 unlessexcludeistrue),excluded_termsat most 200, and a rule may not namecost_price,margin_percentor a reserved profit field. A value out of range is answered with422and anout_of_rangeentry inerror_codes(see Errors).
CORS
The write endpoints above are called from your server and need no CORS. The
public search endpoints are called from the browser and do: preflight requests
are answered for any origin the site's search key works on (its own domain,
with or without www, see Authentication & security), with Access-Control-Allow-Methods, the
requested Access-Control-Allow-Headers, Vary: Origin and an
Access-Control-Max-Age of 10 minutes.
A preflight is resolved from the ?key= query parameter, because a browser
sends no custom headers on a preflight, so X-Search-Key is not available
there. Put the search key in the query string for any request a browser will
preflight (anything that posts JSON, including /assistant).
A preflight for an unknown key, a disabled site or an origin the key does not
work on still returns 204, but without Access-Control-Allow-Origin, and
the browser then blocks the request. The answer is the same whether or not the
site id in the path exists, so a preflight cannot be used to discover sites.