Zum Inhalt springen

Search

Search

https://searcio.com/api/v1

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.


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 q matches and how strongly.
  • Synonyms expand the query, so trainers can match a product that only says sneakers.
  • 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 banner to 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:

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

bash
curl "https://searcio.com/api/v1/sites/123/search?q=runing%20sho&type=product&per_page=10&key=sk_live_xyz"

Response 200 OK

json
{
  "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: runing still finds running. A word that holds a digit, such as an article number or 1001, 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-1001 does not find the AW-1001 that shares its number, while AW-10 still finds AW-1001 as you type. Größe 42 and 4k tv still have a word in them and search as usual.
  • Accents and case are ignored: cafe matches Café.
  • 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 schloss finds "Türschloss" and wolle finds "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 whose languages include one, and to a site that names no language, and only when title is 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: false still 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

http
GET /api/v1/sites/123/storefront-config?key=sk_live_abc

Response 200 OK

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

http
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

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

js
// 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

bash
curl "https://searcio.com/api/v1/sites/123/search/suggest?q=sho&limit=5&filter[lang]=de&key=sk_live_xyz"

Response 200 OK

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

bash
curl "https://searcio.com/api/v1/sites/123/search/popular?limit=10&key=sk_live_xyz"

Response 200 OK

json
{
  "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_terms in 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

bash
curl "https://searcio.com/api/v1/sites/123/search/similar?id=p-1&limit=4&key=sk_live_xyz"

Response 200 OK

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

bash
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

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

bash
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" } }'
text
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 key query parameter (not the header) to avoid CORS preflight requests.
  • Render facets.types as filter chips; clicking one searches again with type=.
  • Show highlight when present; it makes relevance obvious to the visitor. If your results do not show the snippets, send highlight=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.