> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quiz-quail.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quizzes

> Create, manage, and structure quizzes with rounds and questions.

## 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

```bash theme={null}
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".

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

## Update a Quiz

```bash theme={null}
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

```bash theme={null}
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](/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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/guides/themes) and [start a render](/guides/rendering).