Skip to content
Octane AIOctane AI

Quizzes and versions

A quiz on the API is a summary (name, status, the version that is live, page count, links) plus a map of what the draft asks and shows. The editor stays the place where a quiz is built: the API lets you find quizzes, read their shape, save the draft as a version, publish a version, and archive or delete a quiz. The field catalogue is in the reference.

Reads need quizzes:read; archive, unarchive, delete and saving a version need quizzes:write; publishing needs quizzes:publish (see Authentication). Reads cost 1 unit and writes 2 (see Rate limits).

Read one quiz

Terminal window
curl https://api.octaneai.com/v1/quizzes/quiz_2ccb8aebb27c463fa783cafb3bf858e0 \
  -H "Authorization: Bearer $OCTANE_API_KEY"
{
  "id": "quiz_2ccb8aebb27c463fa783cafb3bf858e0",
  "name": "Skin routine finder",
  "status": "published",
  "archived": false,
  "published_version": "ver_15ce0be06b904d0180b1155da02a6c6f",
  "page_count": 3,
  "urls": { "dashboard": "https://editor.octaneai.com/bot_123/editor/2ccb8aeb-b27c-463f-a783-cafb3bf858e0" },
  "structure": {
    "page_count": 3,
    "pages": [
      { "page_key": "welcome", "role": "start", "title": "Find your routine", "component_count": 0 },
      {
        "page_key": "skin", "role": "question", "title": "Your skin", "component_count": 2,
        "components": [
          { "component_key": "multi_choice-k3x9q", "type": "Multiple Choice", "kind": "choice_single", "label": "How does your skin feel by noon?", "required": true,
            "options": [{ "option_id": "b1f4d2e0-6c3a-4f0e-9b2a-1d5c7e8f9a01", "label": "Tight", "scores": ["dry"] }] },
          { "component_key": "sliders-p8m2t", "type": "Slider", "kind": "slider", "label": "How many products do you use?", "range": { "min": 1, "max": 10, "step": 1 } }
        ],
        "jumps": [{ "rule_key": "jump_1", "target_page_key": "results", "condition": { "=": [{ "var": "multi_choice-k3x9q" }, "tight"] } }]
      }
    ],
    "dimensions": [{ "dimension_id": "dry", "label": "Dry skin" }, { "dimension_id": "oily", "label": "Oily skin" }]
  }
}

What to know about the summary:

  • id is the quiz_id every other surface names: the per-quiz analytics, a person’s results and sessions, an export filter, the session and publish webhooks and the storefront events.
  • status (draft or published) and archived are independent: an archived quiz can still be published and live on the store.
  • published_version is the ver_ id live on the store, null on a draft.

What to know about structure:

  • It describes the current draft, not the published version: pages in quiz order with their role (start, question, loading, results), their visibility rule and jump rules, each question with its options and the scoring dimensions an option adds to, a slider’s or number input’s range, a product block’s source, and the quiz’s scoring dimensions. The first 50 pages and the first 40 content components per page are included; layout containers, spacers, progress bars, navigation, buttons and links are left out.
  • It never carries the quiz document: no props, styles, images, HTML, product lists, formula expressions or point values. A field that is null or empty is left off the wire, so read every optional member with a default.
  • The page_key, component_key, option_id and dimension_id values here are the keys a People search term names and the keys answers and points carry everywhere else.

An unknown id, another store’s id and a deleted quiz all answer 404 not_found; every error is a Problem body.

Find quizzes

The list pages by cursor (see Pagination) and filters by status and archived; include=latest_version adds each quiz’s newest saved version (null when it has none), which saves a versions call per quiz.

Terminal window
curl "https://api.octaneai.com/v1/quizzes?status=published&archived=false&include=latest_version&limit=50" \
  -H "Authorization: Bearer $OCTANE_API_KEY"
{
  "data": [
    {
      "id": "quiz_2ccb8aebb27c463fa783cafb3bf858e0",
      "name": "Skin routine finder",
      "status": "published",
      "archived": false,
      "published_version": "ver_15ce0be06b904d0180b1155da02a6c6f",
      "page_count": 3,
      "latest_version": { "id": "ver_15ce0be06b904d0180b1155da02a6c6f", "number": 2, "label": "Autumn launch", "page_count": 3, "published": true, "created_at": "2026-09-01T12:00:00Z" }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

A filter the route does not know (?state=live) is refused with 422 validation_error naming query.state, never ignored. List rows carry no structure.

Versions

A version is a snapshot of the draft. Publishing a version makes it the quiz the store serves; a shopper’s session is pinned to the version that was live when it started, so a publish never changes a quiz mid-run. Every version has a ver_ id and a number: a person’s sessions and results carry the number, the session webhooks and the storefront events carry both.

Versions list newest first; each one is a summary (id, number, label, page_count, published, created_at), not the page tree.

Save the draft and publish it

Saving answers 201 with the new version; the body is optional and names it (label, at most 200 characters; no body saves it with label: null). Publishing answers the updated quiz summary.

Terminal window
curl -X POST https://api.octaneai.com/v1/quizzes/quiz_2ccb8aebb27c463fa783cafb3bf858e0/versions \
  -H "Authorization: Bearer $OCTANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Autumn launch"}'


curl -X POST https://api.octaneai.com/v1/quizzes/quiz_2ccb8aebb27c463fa783cafb3bf858e0/versions/ver_15ce0be06b904d0180b1155da02a6c6f/publish \
  -H "Authorization: Bearer $OCTANE_API_KEY"
{ "id": "ver_15ce0be06b904d0180b1155da02a6c6f", "quiz_id": "quiz_2ccb8aebb27c463fa783cafb3bf858e0", "number": 2, "label": "Autumn launch", "page_count": 3, "published": false, "created_at": "2026-09-01T12:00:00Z" }
  • Publishing a version with no pages answers 409 conflict.
  • A publish fires the quiz.published webhook, makes every cached analytics answer of the store stale, and is recorded under the account of the admin who created the key.
  • Repeating the save creates a second version.

Roll back

Publish any earlier version: the versions list gives you its ver_ id, and the same publish call makes it live. Nothing is deleted; the newer version stays in the list.

Archive and delete

Archiving sets archived: true and answers the summary; the quiz stays published if it was. Unarchiving sets it back. Deleting soft-deletes the quiz and answers 204 with no body: the quiz disappears from the quiz routes, from its analytics routes and as a people filter.

Archiving, unarchiving or saving a version while the AI assistant is editing the quiz answers 409 ai_run_in_progress; retry in a moment.

Sessions

A session is one shopper’s run through a quiz, identified by a sess_ id. There is no session route: sessions are reached through the person who ran them (sessions[] and latest_results[] on a person), through the responses export (one row per session), and as the object of the quiz.started, quiz.finished and quiz.abandoned webhooks. The storefront JS API’s session_id is the same sess_ id. A session carries its status (completed, in_progress or left), the version it ran on, the page it stopped on, the device, channel and country, and the order it led to when one was matched.

Caching

Quiz ownership, status, published version and page count are cached per store for 60 seconds; an archive, unarchive, delete or publish refreshes that quiz at once.