Import a JSON deck from any chatbot

Open the Import page, paste the JSON object your chatbot returned, or choose a .json file. QuizCaddy validates the payload, checks for duplicates, shuffles answer order and saves the deck to your private library.

• Send one JSON object, not an array of question objects.
• Include between 1 and 200 questions in a batch.
• Give every question exactly four distinct options.
• Include at least one step-by-step solution step.
• Keep the request body at or below 4 MB.

The schema is strict. Unknown fields are rejected, so a typo cannot silently change the deck. The example below includes every supported field.

{
  "source": "ChatGPT",
  "topic": "Photosynthesis basics",
  "folder_path": ["Biology", "Photosynthesis"],
  "option_order": "shuffle",
  "questions": [
    {
      "question": "Which process converts light energy into chemical energy in chloroplasts?",
      "options": [
        "Cellular respiration",
        "Photosynthesis",
        "Transpiration",
        "Fermentation"
      ],
      "correct_answer": "Photosynthesis",
      "step_by_step_solution": [
        "Chlorophyll in chloroplasts absorbs light energy.",
        "The captured energy drives glucose synthesis from carbon dioxide and water.",
        "The overall process is photosynthesis."
      ],
      "subject": "Biology",
      "difficulty": "easy",
      "exam": "GCSE"
    }
  ]
}

• source: a short label for where the questions came from, up to 160 characters.
• topic: the deck name, up to 160 characters.
• folder_path: optional array of 1 to 5 names, or a slash-separated string.
• option_order: optional shuffle (default) or keep.
• questions: 1 to 200 question objects.
• question: the full question text, up to 4,000 characters.
• options: exactly four distinct options, each up to 1,500 characters.
• correct_answer: the exact text of one option, up to 1,500 characters.
• step_by_step_solution: 1 to 40 non-empty steps, each up to 4,000 characters.
• subject, difficulty and exam: optional labels of 80 characters or fewer, normalised to lower-case with collapsed whitespace.

QuizCaddy removes one Markdown code fence when the whole payload is wrapped in it. It does not repair trailing commas, strip comments or search for JSON inside prose. If parsing fails, the API reports the exact field path, such as questions.18.correct_answer; the Import page turns that into a question number and field name.

correct_answer must match one of the four options after trimming. If no option matches, the whole batch is rejected with the failing question numbers. Duplicate questions already stored for your account are skipped, not rejected.

folder_path accepts an array of 1 to 5 names or a slash-separated string. The Import page can also override the destination before submission. On the paid plan, valid paths are created or reused and the deck is filed automatically.

On the free plan folders are locked. A path is ignored, the deck is saved unorganised and folder_message explains why. This is a plan outcome, not a JSON error.

• Prefer a two-level Subject/Chapter path in chatbot output. The backend accepts up to five levels; the built-in prompt asks chatbots for at most three.
• Reuse existing folder names exactly when they fit instead of creating near-duplicates.
• Put the exam name in each question's exam field, not in the folder path.
• Omit folder_path when you are unsure. An unorganised deck is still saved.

By default, options are shuffled and the correct answer position is balanced across the batch. Questions that refer to option letters, positions, matching columns or another fixed order pattern are kept as supplied. Use option_order keep only for an official paper with a fixed answer key.

Deduplication uses a SHA-256 hash of the normalised question text, the sorted option set and the correct option text. The same question submitted again is skipped. Changing only the solution steps does not create a distinct question, and a batch containing only matching hashes creates no new deck.

The request body limit is 4 MB. The schema allows up to 200 questions and 40 solution steps per question, but a payload at those extremes can exceed the body limit. Split large decks into smaller batches.

New unique questions count against a rolling 30-day allowance: 100 on the free plan or 10,000 on the paid fair-use plan. Existing questions do not count again. A partial import saves what fits and reports the rest. Deleting a deck does not restore allowance.

Ask the chatbot to return only the JSON object. This compact prompt matches the schema and avoids the most common validation failures:

Return only one valid JSON object with "source", "topic", and "questions".
Each question must have "question", exactly four distinct "options",
"correct_answer" copied exactly from one option, and a non-empty
"step_by_step_solution" array. Add optional "subject", "difficulty",
"exam" and a top-level "folder_path". Do not use Markdown fences,
comments, or text before or after the JSON.

• Copy the correct option text into correct_answer. Do not send A, B, C or D.
• Keep all four options plausible and distinct. Avoid all of the above and none of the above.
• Do not add fields that are not in the schema.
• Remove explanations that appear before or after the JSON object.

That is not valid JSON

Paste the complete object, including the opening and closing braces, and remove any prose or comments outside it. One wrapping Markdown fence is removed automatically.

Validation failed

Read the field path in the error message. Question numbers in the Import page are 1-based, while the API field path is 0-based. Check the option count, duplicate options and the correct_answer text.

No new deck was created

Every question in the batch was already stored for your account. This also happens when the allowance is exhausted before any new question fits. The result message states which reason applied.

Only some questions were added

The rolling allowance was reached while saving the batch. Keep the questions that were added and wait for allowance to release. Do not retry the same batch.