Zum Inhalt springen

Storefront

Quizzes

https://searcio.com/api/v1

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

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

  1. 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.
  2. Render the question's text and image, with its options as buttons.
  3. On a click, merge that option's tags_matched into 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 its keywords, if any, as one more word group (every answered group must be met), and merge its ranges_matched by field in the same way as tags, so a later range on a field replaces an earlier one.
  4. If the clicked option's next_question_id is not null, look up that question by id in the same quiz's questions array and render it next.
  5. If it is null, the quiz has ended. Call GET /api/v1/sites/{site}/search with filter[field][]=value for 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, and range[field]=min:max for 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:

json
{
  "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, every next_question_id pointing at a question of the quiz (or null), no cycle, a label on every option, image links starting with https://, keywords of at most 255 characters, and ranges with at least one numeric bound.
  • A quiz that is published after the request, whether it is being published or was already, also has to pass the publish check: every field in its tags_matched and ranges_matched has to be a facet field of the site (facet_fields in the search configuration), or the visitor's last step would fail.
  • Both checks answer 422, with one sentence per problem under errors.questions, and nothing is saved. A 51st quiz is refused with 422 under errors.quiz.
  • PUT changes 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:

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

html
<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-config before rendering an entry point, and hide it entirely when data.quizzes is empty.
  • Put the search key in the query string: as with every endpoint called from the browser, CORS is resolved from ?key= (see CORS).