Zum Inhalt springen

Getting started

Core concepts

https://searcio.com/api/v1

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 id you 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 Accepted at 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; lang keeps 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.

json
"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: cafe finds "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 fenst finds "Fenstergitter".
  • Autocomplete runs on the start of words, as a visitor types.

Nothing here needs configuring, and search works the same in every language.

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.

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.