Quizzes

Overview

Quizzes are the core resource in Quiz Quail. A quiz contains one or more rounds, and each round contains one or more questions. This guide walks through the full lifecycle of building a quiz programmatically.

Create a Quiz

curl -X POST https://app.quiz-quail.com/api/v1/quizzes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "World Geography Challenge" }'

A new quiz is created in draft status with a default first round (“Round 1”). If you omit title, it defaults to “Untitled Quiz”.

{
  "id": "abc-123",
  "title": "World Geography Challenge",
  "status": "draft",
  "rounds": [
    {
      "id": "round-1",
      "title": "Round 1",
      "order": 0,
      "questions": []
    }
  ]
}

Update a Quiz

curl -X PATCH https://app.quiz-quail.com/api/v1/quizzes/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "World Geography Challenge 2026",
    "description": "Test your knowledge of world capitals and landmarks",
    "question_duration_seconds": 10,
    "answer_duration_seconds": 5
  }'

All fields are optional on update:

Field	Type	Description
`title`	string	Quiz title (cannot be empty)
`description`	string \| null	Quiz description
`intro_subtitle`	string \| null	Subtitle shown on intro screen
`outro_text`	string \| null	Text shown on outro screen
`question_duration_seconds`	number \| null	Default time to display questions
`answer_duration_seconds`	number \| null	Default time to display answers
`fact_duration_seconds`	number \| null	Default time to display fun facts
`hint_timing_percent`	number \| null	When to show hints (0-100% of countdown)
`resolution`	string \| null	Video resolution (e.g. “1920x1080”)
`platform_profile`	string \| null	Platform-specific settings profile

List Quizzes

curl "https://app.quiz-quail.com/api/v1/quizzes?limit=10&sort=updated_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Supports cursor-based pagination with the following query parameters:

Parameter	Default	Description
`limit`	20	Items per page (1-100)
`sort`	`updated_at`	Sort field: `updated_at`, `created_at`, `title`
`order`	`desc`	Sort order: `asc`, `desc`
`status`	—	Filter by status (e.g. `draft`)
`cursor`	—	Pagination cursor from previous response

Get a Quiz

curl https://app.quiz-quail.com/api/v1/quizzes/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the full quiz with all rounds, questions, and the assigned theme.

Delete a Quiz

curl -X DELETE https://app.quiz-quail.com/api/v1/quizzes/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success. This permanently deletes the quiz and all its rounds and questions.

Duplicate a Quiz

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/abc-123/duplicate \
  -H "Authorization: Bearer YOUR_API_KEY"

Creates a deep copy of the quiz including all rounds, questions, and theme assignment. The new quiz title is appended with ” (Copy)” and its status is set to draft.

Rounds

Rounds are ordered containers for questions within a quiz.

Add a Round

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Capital Cities" }'

If title is omitted, it defaults to “Round N” where N is the next number.

Field	Type	Description
`title`	string	Round title
`timer_override`	number \| null	Override the quiz-level question duration for this round

Update a Round

curl -X PATCH https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Famous Landmarks" }'

Delete a Round

curl -X DELETE https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Remaining rounds are automatically re-ordered to fill the gap.

Reorder Rounds

curl -X PUT https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/reorder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "roundIds": ["round-3", "round-1", "round-2"] }'

Pass the complete array of round IDs in the desired order. Each round’s order field is updated to match its array index.

Questions

Questions live inside rounds and represent individual quiz items.

Add a Question

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1/questions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_type": "multiple_choice",
    "content": {
      "text": "What is the capital of France?",
      "options": ["London", "Paris", "Berlin", "Madrid"],
      "correctOptionIndex": 1
    },
    "countdown_seconds": 10,
    "hint": "It is known as the City of Light",
    "fact": "Paris has been the capital of France since 987 AD"
  }'

Field	Type	Description
`question_type`	string	Required. One of the 13 question types (see below)
`content`	object	Type-specific content. If omitted, default content is generated
`countdown_seconds`	number	Time limit for this question (default: 5)
`difficulty`	number \| null	Difficulty level (1-5)
`hint`	string \| null	Hint text shown during countdown
`fact`	string \| null	Fun fact shown after the answer is revealed

Question Types

Quiz Quail supports 13 question types, each with its own content schema:

Type	Content Fields	Description
`multiple_choice`	`text`, `options[]`, `correctOptionIndex`	Standard multiple choice (2-6 options)
`true_false`	`text`, `correctAnswer`	True or false
`short_answer`	`text`, `correctAnswer`	Free-text answer
`image`	`text`, `imageUrl`, `options[]`, `correctOptionIndex`	Image-based multiple choice
`ranking`	`text`, `items[]`, `correctOrder[]`	Put items in the correct order
`numeric`	`text`, `correctAnswer`	Numeric answer
`open_reveal`	`text`, `revealAnswer`	Open-ended with a revealed answer
`video`	`text`, `videoUrl`, `options[]`, `correctOptionIndex`	Video-based multiple choice
`audio`	`text`, `audioUrl`, `options[]`, `correctOptionIndex`	Audio-based multiple choice
`multi_video`	`text`, `videoUrls[]`, `options[]`, `correctOptionIndex`	Multiple video clips
`multi_audio`	`text`, `audioUrls[]`, `options[]`, `correctOptionIndex`	Multiple audio clips
`progressive_reveal`	`text`, `mediaUrl`, `options[]`, `correctOptionIndex`	Gradually revealed media
`emoji`	`text`, `emojis`, `options[]`, `correctOptionIndex`	Emoji-based clue

Update a Question

curl -X PATCH \
  https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1/questions/q-1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "text": "What is the capital of Germany?",
      "options": ["Munich", "Berlin", "Hamburg", "Frankfurt"],
      "correctOptionIndex": 1
    }
  }'

Delete a Question

curl -X DELETE \
  https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1/questions/q-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Remaining questions are automatically re-ordered.

Reorder Questions

curl -X PUT \
  https://app.quiz-quail.com/api/v1/quizzes/abc-123/rounds/round-1/questions/reorder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "questionIds": ["q-3", "q-1", "q-2"] }'

Example: Build a Complete Quiz

This step-by-step example creates a geography quiz with two rounds.

Step 1: Create the quiz

curl -X POST https://app.quiz-quail.com/api/v1/quizzes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Geography Quiz"
  }'

Save the returned id (e.g. quiz-001) and the default round ID (e.g. round-001).

Step 2: Add questions to Round 1

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/quiz-001/rounds/round-001/questions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_type": "multiple_choice",
    "content": {
      "text": "What is the largest country by area?",
      "options": ["Canada", "China", "Russia", "United States"],
      "correctOptionIndex": 2
    },
    "countdown_seconds": 15,
    "fact": "Russia spans 11 time zones"
  }'

Step 3: Add a second round

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/quiz-001/rounds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "True or False" }'

Save the returned round ID (e.g. round-002).

Step 4: Add a true/false question

curl -X POST https://app.quiz-quail.com/api/v1/quizzes/quiz-001/rounds/round-002/questions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_type": "true_false",
    "content": {
      "text": "The Great Wall of China is visible from space",
      "correctAnswer": false
    },
    "fact": "This is a common myth - it is not visible to the naked eye from low Earth orbit"
  }'

Step 5: Assign a theme and render

Once your quiz structure is complete, assign a theme and start a render.

Getting Started

Core Concepts

Guides

Overview

Create a Quiz

Update a Quiz

List Quizzes

Get a Quiz

Delete a Quiz

Duplicate a Quiz

Rounds

Add a Round

Update a Round

Delete a Round

Reorder Rounds

Questions

Add a Question

Question Types

Update a Question

Delete a Question

Reorder Questions

Example: Build a Complete Quiz

Step 1: Create the quiz

Step 2: Add questions to Round 1

Step 3: Add a second round

Step 4: Add a true/false question

Step 5: Assign a theme and render

Getting Started

Core Concepts

Guides

Documentation Index

​Overview

​Create a Quiz

​Update a Quiz

​List Quizzes

​Get a Quiz

​Delete a Quiz

​Duplicate a Quiz

​Rounds

​Add a Round

​Update a Round

​Delete a Round

​Reorder Rounds

​Questions

​Add a Question

​Question Types

​Update a Question

​Delete a Question

​Reorder Questions

​Example: Build a Complete Quiz

​Step 1: Create the quiz

​Step 2: Add questions to Round 1

​Step 3: Add a second round

​Step 4: Add a true/false question

​Step 5: Assign a theme and render

Overview

Create a Quiz

Update a Quiz

List Quizzes

Get a Quiz

Delete a Quiz

Duplicate a Quiz

Rounds

Add a Round

Update a Round

Delete a Round

Reorder Rounds

Questions

Add a Question

Question Types

Update a Question

Delete a Question

Reorder Questions

Example: Build a Complete Quiz

Step 1: Create the quiz

Step 2: Add questions to Round 1

Step 3: Add a second round

Step 4: Add a true/false question

Step 5: Assign a theme and render