Getting started
Core concepts
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
The handful of ideas the rest of this reference builds on: what a site is, how content gets into its index, what shapes the results, and what is counted against a plan. Read this once before the endpoint pages; each section links to the reference that goes deeper.
Sites and keys
A site is one website connected to Searcio: a shop, a blog, a help center. Each site is isolated from every other: its own search index, its own search settings, its own credentials. Usage is counted per site and added up for the account that owns it.
Every site has two kinds of credentials, for two places:
| Credential | Where it lives | What it can do |
|---|---|---|
| Write key + write secret | Your server only | Index and remove documents, read and change the search configuration, manage quizzes |
| Search key | The browser, in public | Search, autocomplete, recommendations, the AI assistant |
The search key is safe in a page's source because it can only read, and because it works only on its own site's domain: a browser request from any other website is refused. See Authentication & security.
A site moves through three states:
| Status | Meaning |
|---|---|
pending |
Created, nothing indexed yet. The keys already work. |
connected |
Has indexed content and is serving search. |
disabled |
Indexing and search are both refused with 403. |
Both kinds of key identify the site on their own, so every endpoint also works without the site id in its path. See Base URL.
Documents and the index
You keep a site's index in step with your platform by sending documents: products, posts, pages, anything a visitor should find.
- The id is yours. The
idyou send is the document's key. Sending the same id again replaces the document (an upsert); deleting it by id removes it. - Indexing is asynchronous. Write requests answer
202 Acceptedat once and the work happens in the background, usually within seconds. - Any shape. A handful of fields have a meaning to Searcio (
title,content,url,image,price,type,lang, …); everything else you send is kept, searchable when you list it as a searchable field, and usable as a filter when you list it as a facet. - Types and languages.
type(product,post, …) lets results be boosted and filtered by kind;langkeeps a multilingual shop's languages apart. See Languages & currencies.
See Documents and Document schema.
Search settings
Each site has search settings that shape its results without any code. The site owner edits them in the dashboard, and a plugin can read and change them through the search configuration endpoints, so a setting changed in either place shows in both.
Searchable fields and weights
Which document fields are searched, and how much a match in each counts. A match in a field with weight 5 counts five times as much as one in a field with weight 1:
| Field | Weight | Effect |
|---|---|---|
title |
5 | A match in the title dominates. |
sku |
3 | Product codes rank well. |
content |
1 | Body text helps, but less. |
Synonyms
Groups of words that mean the same thing for this shop, such as
sneaker, trainer, runner. A search containing one word of a group also finds
documents that only use another. Synonyms are matched as written, without typo
tolerance, and a synonym of several words ("running shoes") needs all of them.
Type boosts
Rank some content types above others: a shop usually lifts product above
post, so products come first and articles still appear.
Facets
The fields visitors can filter by, such as brand, color or categories.
Every search returns each facet's values with how many results carry them, and
filter[field]=value narrows the results. When a visitor picks several values
of one facet, the site's facet_match decides whether a result needs any of
them (the default, right for colour or brand) or all of them (right for
features such as organic and vegan). See Search.
Category trees
A shop's categories form a tree, and two categories can share a name under
different parents: "MTS Technik" under "Gewindefahrwerke" and again under
"Sturzdomlager". Sent by name, they are one facet value with their counts added
together. Send the tree instead in a field whose name ends in _paths, such as
category_paths: each category as its whole path from the top, the levels
joined by >, with one value for every level above it.
"category_paths": [
"Fahrwerke",
"Fahrwerke > Gewindefahrwerke",
"Fahrwerke > Gewindefahrwerke > MTS Technik"
]Every path is a value of its own, so each category keeps its own count, and a
filter on Fahrwerke > Gewindefahrwerke finds everything filed under it. On
/search, each value of such a field comes with the
name to show and the path of its parent, and the field returns all of its
values rather than the most frequent fifty, so the whole tree can be drawn. The
order of the levels is yours: values come back by count, and the storefront
sorts each level the way the shop does.
Merchandising rules
Curated results for chosen searches or category pages. A rule fires on a search term, on an active filter value, or both, and can pin products to the top, hide products, and return a banner for the storefront to show. Rules can be limited to one language. The first matching rule applies.
Search redirects
A search term that should open a page instead of showing results, such as a voucher code or "returns". A redirect matches the whole term exactly, ignoring case, and answers before any search runs, so it is not counted as a search.
Text analysis
Every index uses the same analysis, so behaviour is predictable on every site:
- Accents and case are ignored:
cafefinds "Café". - Typos are forgiven: one typo from 4 letters, two from 8. The first two letters of a word are taken as typed, so "sneaker" does not find "speaker".
- Prefixes: the last word of a search also matches the start of longer words
once it has 3 letters, so
fenstfinds "Fenstergitter". - Autocomplete runs on the start of words, as a visitor types.
Nothing here needs configuring, and search works the same in every language.
AI search
On plans that include it, a site can switch on AI search: every search then combines the keyword results above with semantic results, which match on meaning rather than on the exact words, so "waterproof jacket" can find a rain coat. Nothing changes for the client; the same endpoints return better results.
- A semantic match has to be genuinely close to count, so a search with few keyword matches is not padded with unrelated products, and the facets count only what passes.
- Searches sent while the shopper is still typing (
live=1) use the semantic side only when it can answer at once, so typing never waits for it; the search sent when the shopper stops typing always uses it. Autocomplete keeps to keyword matching. - If the semantic side cannot answer, the search returns its keyword results rather than an error.
AI visual tagging
With AI visual tagging on, a vision model looks at each product image while
the product is indexed and adds descriptive tags (colour, material, style), so a
product with a thin title can still be found by what it looks like. The tags are
written in the product's language: the one its lang names, or else the
language of its title. Turning tagging on also tags the products already
indexed, in the background.
Visual search
With visual search on, a shopper can search with a photo instead of words. See Visual search.
Personalized ranking
With personalized ranking on, the products people click most for a search
rise for everyone who runs that search. It works from the anonymous click
reports the storefront already sends, attributed to a search and never to a
person: no cookie, no profile. Relevance stays the main signal, and pinned
products keep the top. Report clicks with POST /search/click.
Search analytics
Every search is recorded with its term, its result count and the language of the page. No name, cookie or account is attached; where address logging is switched on, the visitor's IP is kept only as a salted hash. Together with the click reports this powers the site owner's statistics (top searches, searches that found nothing, click-through rate), the popular searches a storefront can show, and the analytics tools of the MCP server.
Usage and limits
An account is measured against its plan on five axes:
| Metric | How it is counted | Resets |
|---|---|---|
| Searches | Each search that runs, including the ones the AI assistant runs while answering | Monthly |
| AI messages | Each AI assistant reply and other AI action | Monthly |
| Documents | Indexed documents across the account's sites | Live count |
| Sites | Connected sites | Live count |
| Members | Team members | Live count |
Limits are checked before the work happens. A request over a limit is refused
with 429 and a body naming the metric, never partially applied. Only full
searches (GET /search, photo searches, and the searches the assistant runs)
count as searches; autocomplete, popular searches, similar products,
redirects, result cards and quizzes do not. Read the live
figures from Health to warn users before they reach a limit. See
Errors & rate limits.
Versioning
The API is versioned in its path: /api/v1. These docs are for 1.x, every
release of v1.
Within v1, changes only add: new endpoints, new optional parameters, new fields
in responses and new values in lists that are documented as open. A v1 client
keeps working through all of them, provided it ignores fields it does not know.
Anything that would break a client (removing or renaming a field, changing a
type, making an optional parameter required) ships as /api/v2, with its own
docs, while v1 keeps working.