Zum Inhalt springen

Search

Search configuration

https://searcio.com/api/v1

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.

bash
curl "https://searcio.com/api/v1/search-config" \
  -H "X-Write-Key: $WK" -H "X-Write-Secret: $WS"

Response: 200 OK

json
{
  "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.

json
{
  "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.

json
{ "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).

json
{
  "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.

bash
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 status are cleared.
  • Enabling a feature the plan does not include fails with 422 and a field error on features.<name>.enabled, not with 403: 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.

bash
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:

json
{
  "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.
  • languages entries are language codes (de, en, pt-BR). The list is rejected with a languages error when it exceeds the plan's language limit (see Health for the limit).
  • merchandising accepts at most 50 rules, and pinned and hidden at most 50 ids each.
  • redirects accepts at most 50 rules; url must start with http://, https:// or /.
  • profit_ranking is sent whole: enabled, strength (1 to 50) and target (0.1 to 100) are required with it, listings is a boolean, min_profit is 0 to 1,000,000, rules holds at most 100 entries (each with a target of 0.1 to 100 unless exclude is true), excluded_terms at most 200, and a rule may not name cost_price, margin_percent or a reserved profit field. A value out of range is answered with 422 and an out_of_range entry in error_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.