Storefront
Quizzes
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Merchants build short guided quizzes in the Searcio dashboard. A quiz is a directed graph of questions in which each answer can lead to a different next question and narrow the products in one of three ways: by tagging a catalogue attribute (for example "style: casual"), by asking for words the products must contain (for example "Panzerriegel"), or by setting a price range. A widget walks the visitor through the quiz entirely in the browser and calls the search API only once the quiz ends, filtered by everything the visitor answered.
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.
Authentication: the search key (?key=sk_… or X-Search-Key), as for
GET /search, and works only on the site's own domain. A plugin that
builds quizzes for the merchant uses the
management endpoints with the write
credentials instead.
GET /quizzes
| Param | Type | Default | Notes |
|---|---|---|---|
id |
integer | None | Return only this quiz instead of every published one. |
filter[lang] |
string | None | The page's language on a multilingual shop: only quizzes in that language, and quizzes for every language (lang: null), are returned. Without it, every published quiz is listed. |
key |
string | None | The search key (or X-Search-Key). |
Returns every published quiz on the site, each with its full question graph, so the widget can run the whole flow in the browser and only needs the network again at the end. Responses are served from a cache on the server and are not metered as searches.
Response 200 OK
{
"quizzes": [
{
"id": 4,
"name": "Find your fit",
"lang": "en",
"questions": [
{
"id": "style",
"text": "What's your style?",
"image": "https://cdn.example.com/style.jpg",
"options": [
{
"id": "casual",
"label": "Casual",
"next_question_id": "size",
"tags_matched": [{ "field": "style", "value": "casual" }]
},
{
"id": "formal",
"label": "Formal",
"next_question_id": "size",
"tags_matched": [{ "field": "style", "value": "formal" }]
}
]
},
{
"id": "size",
"text": "What size?",
"options": [
{
"id": "m",
"label": "Medium",
"next_question_id": null,
"tags_matched": [{ "field": "size", "value": "m" }]
},
{
"id": "trail-budget",
"label": "Trail shoes under €100",
"next_question_id": null,
"tags_matched": [],
"keywords": "trail, offroad",
"ranges_matched": [{ "field": "price", "min": null, "max": 100 }]
}
]
}
]
}
]
}| Field | Meaning |
|---|---|
lang |
The quiz's language code, or null when it is offered in every language. Set in the quiz settings in the Searcio dashboard. |
questions[].id |
The question's id, unique within the quiz. next_question_id refers to it; it is never shown to the visitor. |
questions[].text |
The question shown to the visitor. |
questions[].image |
Optional image URL shown alongside the question. |
questions[].options[].label |
The answer text on the button the visitor picks. |
questions[].options[].next_question_id |
The next question's id, or null to end the quiz with this answer. |
questions[].options[].tags_matched |
Zero or more {field, value} pairs added to the final search filter when this answer is picked. |
questions[].options[].keywords |
Optional. Words the product's name (or SKU) must contain, as alternatives separated by commas, of which one must match ("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"). Absent or null when the answer asks for no words. |
questions[].options[].ranges_matched |
Optional. Zero or more {field, min, max} numeric ranges, where either bound may be null; for example, a budget answer on price. |
The response has no status field: every quiz returned is published, and drafts never appear here.
Widget flow contract
- Fetch the quiz list once per page load and start at the first question in the array. There is no separate start pointer: the array is in authoring order, and its first question is the entry point.
- Render the question's
textandimage, with its options as buttons. - On a click, merge that option's
tags_matchedinto an accumulator: a plain{field: value}map in which a later answer for a field overwrites an earlier one, because the visitor's most recent choice is the one that counts. Keep itskeywords, if any, as one more word group (every answered group must be met), and merge itsranges_matchedby field in the same way as tags, so a later range on a field replaces an earlier one. - If the clicked option's
next_question_idis notnull, look up that question byidin the same quiz'squestionsarray and render it next. - If it is
null, the quiz has ended. CallGET /api/v1/sites/{site}/searchwithfilter[field][]=valuefor every value in the accumulator (the list form keeps a value containing a comma whole; joining values with commas also works when none contains one),keywords[]=…once per word group, andrange[field]=min:maxfor every range (leave out a missing bound:range[price]=:100), and render the results.
A widget written before keywords and ranges_matched existed ignores them
and still runs the quiz; its results are only broader, never broken.
A visitor can never reach a dead end: publishing rejects any quiz that contains
a cycle (a loop with no path to null) or a next_question_id that points
nowhere, and checks again that every tags_matched and ranges_matched field
is still a configured facet of the site.
Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
403 |
Site disabled, or Origin not the site's own domain |
422 |
id is not an integer |
A site with no published quizzes returns { "quizzes": [] }, not an error.
Hide the quiz entry point when the list is empty instead of treating it as a
failure.
Managing quizzes from a plugin
A plugin can create and edit the merchant's quizzes as the Searcio dashboard
does, with the same question graph (the shape shown under
GET /quizzes), the same checks and the same limit of
50 quizzes per site. A quiz created through the API appears in the
dashboard, and the other way round.
The base URL is the same as above. Authentication uses the
write credentials, X-Write-Key and X-Write-Secret (see
Authentication & security), never the public
search key. /quiz-templates is the merchant's editable set, drafts included;
the storefront keeps reading the published ones from /quizzes.
| Method | Path | Body | Answer |
|---|---|---|---|
GET |
/quiz-templates |
{ quizzes: [{ id, name, status, lang, question_count, updated_at }], limit } |
|
POST |
/quiz-templates |
{ name, lang?, status?, questions? } |
201 and the quiz |
GET |
/quiz-templates/{id} |
The quiz | |
PUT |
/quiz-templates/{id} |
Any of { name, lang, status, questions } |
The quiz |
DELETE |
/quiz-templates/{id} |
204 |
|
GET |
/quiz-templates/facet-values |
{ values: { field: [{ value, count }] } } |
|
POST |
/quiz-templates/endings |
{ questions, lang? } |
Every way the graph can end, with its product count |
A quiz is returned as:
{
"id": 12,
"name": "Find your lock",
"status": "draft",
"lang": "de",
"questions": [ … ],
"created_at": "2026-11-07T10:12:00+00:00",
"updated_at": "2026-11-07T10:12:00+00:00"
}| Field | Notes |
|---|---|
name |
Required on create, at most 255 characters. |
lang |
A language code (de, en, pt-BR), or null for every language. |
status |
draft (the default) or published. PUT with published publishes the quiz; PUT with draft unpublishes it. |
questions |
The question graph. Without it, a new quiz starts as a draft with one empty question. |
Checks.
questions, whenever it is sent, has to be a valid graph: at most 30 questions of at most 8 options each, unique question ids, everynext_question_idpointing at a question of the quiz (ornull), no cycle, a label on every option, image links starting withhttps://,keywordsof at most 255 characters, and ranges with at least one numeric bound.- A quiz that is
publishedafter the request, whether it is being published or was already, also has to pass the publish check: every field in itstags_matchedandranges_matchedhas to be a facet field of the site (facet_fieldsin the search configuration), or the visitor's last step would fail. - Both checks answer
422, with one sentence per problem undererrors.questions, and nothing is saved. A 51st quiz is refused with422undererrors.quiz. PUTchanges only the keys it sends:{ "status": "published" }publishes the quiz as it is, and{ "lang": null }clears its language.
Building answers. facet-values lists up to 200 values per facet field,
with the number of documents that carry each, so answers can tag values that
exist (the lists are empty when the index cannot be reached). endings takes a
graph, saved or not, and returns every answer path with the number of products
it finds:
{
"endings": [
{ "answers": [{ "question": "What do you want to lock?", "answer": "A door" }, { "question": "Which brand?", "answer": "ABUS" }], "count": 1, "unknown_fields": [] }
],
"truncated": false
}Send the quiz's lang with the graph: each ending is then counted as the quiz
runs, on a page in that language (documents without a language still count).
Without it, products in every language are counted. An ending with count: 0
is a dead end for the visitor; change its answers before publishing. count is null when the path uses a field that is not a
facet of the site (listed in unknown_fields); such a quiz cannot be
published. At most 60 endings are listed, and truncated says whether there
were more.
Errors
| Status | When |
|---|---|
401 |
Missing or wrong write credentials (the search key is refused too) |
404 |
No quiz with that id on this site |
422 |
Invalid fields, an invalid graph, a failed publish check, or the limit of 50 quizzes |
Frontend integration: a minimal quiz widget
This example uses no dependencies, only fetch and the DOM. It renders one quiz
from start to finish and runs the final filtered search.
<div id="quiz-widget"></div>
<script>
const KEY = 'sk_live_xyz';
const BASE = 'https://searcio.com/api/v1/sites/123';
const root = document.getElementById('quiz-widget');
const tags = {};
function renderQuestion(quiz, question) {
root.innerHTML = `
<p>${question.text}</p>
${question.image ? `<img src="${question.image}" alt="" />` : ''}
${question.options
.map((option, i) => `<button data-i="${i}">${option.label}</button>`)
.join('')}
`;
root.querySelectorAll('button').forEach((button) => {
button.addEventListener('click', () => {
const option = question.options[Number(button.dataset.i)];
for (const tag of option.tags_matched) {
tags[tag.field] = tag.value;
}
if (option.next_question_id === null) {
finish();
return;
}
const next = quiz.questions.find(
(q) => q.id === option.next_question_id,
);
renderQuestion(quiz, next);
});
});
}
async function finish() {
root.innerHTML = '<p>Finding your matches…</p>';
const params = new URLSearchParams({ key: KEY });
for (const [field, value] of Object.entries(tags)) {
params.set(`filter[${field}]`, value);
}
const response = await fetch(`${BASE}/search?${params}`);
const data = await response.json();
root.innerHTML = data.hits.length
? data.hits
.map((hit) => `<a href="${hit.source.url}">${hit.source.title}</a>`)
.join('')
: '<p>No matches - try different answers.</p>';
}
fetch(`${BASE}/quizzes?key=${KEY}`)
.then((response) => response.json())
.then((data) => {
const quiz = data.quizzes[0];
if (quiz) {
renderQuestion(quiz, quiz.questions[0]);
}
});
</script>- Fetch the quiz list once, not per question; the whole graph is already in the response.
- Degrade gracefully: check the quiz capability in
/storefront-configbefore rendering an entry point, and hide it entirely whendata.quizzesis empty. - Put the search key in the query string: as with every endpoint called
from the browser, CORS is resolved from
?key=(see CORS).