### Browse Questions Response

Source: https://quizapi.io/docs/questions

Example JSON response containing a list of questions and pagination metadata.

```json
{
  "success": true,
  "data": [
    {
      "id": "ques_xyz789",
      "text": "What is the typeof null in JavaScript?",
      "type": "MULTIPLE_CHOICE",
      "difficulty": "MEDIUM",
      "explanation": "typeof null returns 'object' due to a legacy bug.",
      "category": "Programming",
      "tags": ["javascript", "fundamentals"],
      "quizId": "quiz_abc123",
      "quizTitle": "JavaScript Essentials",
      "answers": [
        { "id": "ans_1", "text": "null", "isCorrect": false },
        { "id": "ans_2", "text": "object", "isCorrect": true },
        { "id": "ans_3", "text": "undefined", "isCorrect": false },
        { "id": "ans_4", "text": "string", "isCorrect": false }
      ]
    }
  ],
  "meta": {
    "total": 23,
    "pageTotal": 1,
    "page": 1,
    "lastPage": 3,
    "limit": 10,
    "offset": 0,
    "links": {
      "first": "/api/v1/questions?...&offset=0&limit=10",
      "last": "/api/v1/questions?...&offset=20&limit=10",
      "next": "/api/v1/questions?...&offset=10&limit=10",
      "prev": null
    }
  }
}
```

--------------------------------

### Full Quiz Integration Example

Source: https://quizapi.io/docs/embeds

A complete HTML implementation including configuration data attributes and a results display banner.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Quiz Page</title>
  <style>
    .quiz-container {
      max-width: 800px;
      margin: 2rem auto;
      padding: 0 1rem;
    }
    .results-banner {
      display: none;
      padding: 1rem;
      margin-top: 1rem;
      border-radius: 8px;
      background: #f0fdf4;
      border: 1px solid #bbf7d0;
      color: #166534;
    }
  </style>
</head>
<body>
  <div class="quiz-container">
    <h1>JavaScript Fundamentals Quiz</h1>
    <p>Test your knowledge of JavaScript basics.</p>

    <div
      id="quizapi-embed"
      data-quiz-id="quiz_abc123"
      data-theme="auto"
      data-color="#6366f1"
      data-show-leaderboard="true"
    ></div>

    <div class="results-banner" id="results">
      You scored <strong id="score"></strong> out of
      <strong id="total"></strong>!
    </div>
  </div>

  <script src="https://quizapi.io/embed.js"></script>
  <script>
    window.addEventListener("quizapi:complete", function (event) {
      var results = document.getElementById("results");
      document.getElementById("score").textContent = event.detail.score;
      document.getElementById("total").textContent = event.detail.totalQuestions;
      results.style.display = "block";
    });
  </script>
</body>
</html>
```

--------------------------------

### Quiz Created Payload Example

Source: https://quizapi.io/docs/webhooks

JSON structure for the quiz.created event payload.

```json
{
  "id": "evt_ghi789jkl012",
  "event": "quiz.created",
  "created_at": "2025-01-16T10:00:00Z",
  "data": {
    "quiz_id": "quiz_new456",
    "title": "React Hooks Quiz",
    "category": "programming",
    "created_by": "user_abc123"
  }
}
```

--------------------------------

### Browse Questions Request

Source: https://quizapi.io/docs/questions

Example cURL request to fetch filtered questions with authentication.

```bash
curl -X GET "https://quizapi.io/api/v1/questions?category=Programming,DevOps&difficulty=EASY,MEDIUM&type=MULTIPLE_CHOICE&tags=javascript,react&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Successful API Response

Source: https://quizapi.io/docs/rate-limits

Example of a standard 200 OK response structure.

```http
HTTP/1.1 200 OK



{
  "success": true,
  "data": [ ... ]
}
```

--------------------------------

### GET /quizzes

Source: https://quizapi.io/docs

Fetches a list of available quizzes from the platform.

```APIDOC
## GET /quizzes

### Description
Retrieves a paginated list of quizzes available on the platform.

### Method
GET

### Endpoint
https://quizapi.io/api/v1/quizzes

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of quizzes to return in the response.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of quiz objects.
- **meta** (object) - Pagination metadata including total, limit, and offset.

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "JavaScript Fundamentals",
      "description": "Test your knowledge of JS basics",
      "category": "programming",
      "difficulty": "MEDIUM",
      "tags": ["javascript", "web"],
      "questionCount": 10,
      "plays": 1250
    }
  ],
  "meta": {
    "total": 42,
    "limit": 5,
    "offset": 0
  }
}
```

--------------------------------

### List Quizzes Response

Source: https://quizapi.io/docs/quizzes

Example JSON response containing a list of quiz objects and metadata for pagination.

```json
{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "JavaScript Fundamentals",
      "slug": "javascript-fundamentals",
      "description": "Test your knowledge of JS basics",
      "category": "Programming",
      "categoryId": "cat_javascript",
      "categoryName": "JavaScript",
      "categorySlug": "javascript",
      "topic": "Programming",
      "topicSlug": "programming",
      "difficulty": "MEDIUM",
      "tags": ["javascript", "web"],
      "questionCount": 10,
      "plays": 1250
    },
    {
      "id": "quiz_def456",
      "title": "Python Data Structures",
      "slug": "python-data-structures",
      "description": "Test your knowledge of Python data structures",
      "category": "Programming",
      "categoryId": "cat_python",
      "categoryName": "Python",
      "categorySlug": "python",
      "topic": "Programming",
      "topicSlug": "programming",
      "difficulty": "EASY",
      "tags": ["python", "data-structures"],
      "questionCount": 15,
      "plays": 830
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}
```

--------------------------------

### Quiz Completed Payload Example

Source: https://quizapi.io/docs/webhooks

JSON structure for the quiz.completed event payload.

```json
{
  "id": "evt_abc123def456",
  "event": "quiz.completed",
  "created_at": "2025-01-16T14:30:00Z",
  "data": {
    "quiz_id": "quiz_abc123",
    "user_id": "user_xyz789",
    "score": 8,
    "total_questions": 10,
    "time_spent": 245,
    "completed_at": "2025-01-16T14:30:00Z"
  }
}
```

--------------------------------

### List Topics and Categories via cURL

Source: https://quizapi.io/docs/categories

Retrieve the full topic and category hierarchy using a GET request. This endpoint is public and does not require authentication.

```bash
curl -X GET "https://quizapi.io/api/v1/categories" \
  -H "Content-Type: application/json"
```

--------------------------------

### API Response Structure

Source: https://quizapi.io/docs

Example of the standard JSON response format returned by list endpoints, including data and pagination metadata.

```json
{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "JavaScript Fundamentals",
      "description": "Test your knowledge of JS basics",
      "category": "programming",
      "difficulty": "MEDIUM",
      "tags": ["javascript", "web"],
      "questionCount": 10,
      "plays": 1250
    }
  ],
  "meta": {
    "total": 42,
    "limit": 5,
    "offset": 0
  }
}
```

--------------------------------

### Rate Limited Response

Source: https://quizapi.io/docs/rate-limits

Example of a 429 Too Many Requests response structure.

```http
HTTP/1.1 429 Too Many Requests



{
  "success": false,
  "error": "Rate limit exceeded. Please try again later."
}
```

--------------------------------

### Quiz Questions API Response Structure

Source: https://quizapi.io/docs/questions

Example JSON response containing a list of question objects with metadata and answer options.

```json
{
  "success": true,
  "data": [
    {
      "id": "ques_xyz789",
      "quizId": "quiz_abc123",
      "text": "What is the typeof null in JavaScript?",
      "type": "MULTIPLE_CHOICE",
      "difficulty": "MEDIUM",
      "explanation": "typeof null returns 'object' due to a legacy bug.",
      "category": "Programming",
      "answers": [
        { "id": "ans_1", "text": "null", "isCorrect": false },
        { "id": "ans_2", "text": "object", "isCorrect": true },
        { "id": "ans_3", "text": "undefined", "isCorrect": false },
        { "id": "ans_4", "text": "string", "isCorrect": false }
      ]
    }
  ],
  "meta": {
    "total": 10,
    "quizId": "quiz_abc123"
  }
}
```

--------------------------------

### Webhook Signature Verification

Source: https://quizapi.io/docs/webhooks

Example implementation of webhook signature verification using Node.js and Express to ensure requests originate from QuizAPI.

```APIDOC
## Webhook Signature Verification

### Description
Verify the `X-QuizAPI-Signature` header using HMAC-SHA256 to ensure the integrity and authenticity of incoming webhook events.

### Implementation Details
- **Algorithm**: HMAC-SHA256
- **Header**: `X-QuizAPI-Signature`
- **Security Note**: Always use `crypto.timingSafeEqual` to prevent timing attacks when comparing signatures.

### Example (Node.js/Express)
```javascript
const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const expected = `sha256=${expectedSignature}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post("/webhooks/quizapi", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-quizapi-signature"];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(payload);
  // Process event...
  res.status(200).json({ received: true });
});
```
```

--------------------------------

### GET /api/v1/questions

Source: https://quizapi.io/docs/questions

Retrieves a list of questions across all published quizzes, supporting various filters and pagination.

```APIDOC
## GET /api/v1/questions

### Description
Browse questions across all published quizzes. When called without a quiz_id, this endpoint returns paginated questions filtered by category, difficulty, type, and tags.

### Method
GET

### Endpoint
/api/v1/questions

### Parameters
#### Query Parameters
- **category** (string) - Optional - Filter by quiz category. Supports comma-separated values.
- **difficulty** (string) - Optional - Filter by difficulty. Supports comma-separated values.
- **type** (string) - Optional - Filter by question type. Supports comma-separated values.
- **tags** (string) - Optional - Comma-separated list of tags to match.
- **limit** (integer) - Optional - Number of questions to return per page (1–50). Default: 10.
- **offset** (integer) - Optional - Number of questions to skip for pagination. Default: 0.
- **random** (string) - Optional - Set to "true" to shuffle the returned questions randomly.

### Request Example
curl -X GET "https://quizapi.io/api/v1/questions?category=Programming,DevOps&difficulty=EASY,MEDIUM&type=MULTIPLE_CHOICE&tags=javascript,react&limit=10&offset=0" -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - List of question objects.
- **meta** (object) - Pagination metadata object.

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "ques_xyz789",
      "text": "What is the typeof null in JavaScript?",
      "type": "MULTIPLE_CHOICE",
      "difficulty": "MEDIUM",
      "explanation": "typeof null returns 'object' due to a legacy bug.",
      "category": "Programming",
      "tags": ["javascript", "fundamentals"],
      "quizId": "quiz_abc123",
      "quizTitle": "JavaScript Essentials",
      "answers": [
        { "id": "ans_1", "text": "null", "isCorrect": false },
        { "id": "ans_2", "text": "object", "isCorrect": true },
        { "id": "ans_3", "text": "undefined", "isCorrect": false },
        { "id": "ans_4", "text": "string", "isCorrect": false }
      ]
    }
  ],
  "meta": {
    "total": 23,
    "pageTotal": 1,
    "page": 1,
    "lastPage": 3,
    "limit": 10,
    "offset": 0,
    "links": {
      "first": "/api/v1/questions?...&offset=0&limit=10",
      "last": "/api/v1/questions?...&offset=20&limit=10",
      "next": "/api/v1/questions?...&offset=10&limit=10",
      "prev": null
    }
  }
}
```

--------------------------------

### GET /api/v1/quizzes/{id}

Source: https://quizapi.io/docs/quizzes

Retrieves a single quiz by its ID, including its full questions array and settings.

```APIDOC
## GET /api/v1/quizzes/{id}

### Description
Retrieves a single quiz by its ID, including its full questions array and settings.

### Method
GET

### Endpoint
https://quizapi.io/api/v1/quizzes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The quiz ID (e.g., quiz_abc123)

### Request Example
curl -X GET "https://quizapi.io/api/v1/quizzes/quiz_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - The quiz object containing details, settings, and questions

#### Response Example
{
  "success": true,
  "data": {
    "id": "quiz_abc123",
    "title": "JavaScript Fundamentals",
    "slug": "javascript-fundamentals",
    "description": "Test your knowledge of JS basics",
    "category": "Programming",
    "categoryId": "cat_javascript",
    "categoryName": "JavaScript",
    "categorySlug": "javascript",
    "topic": "Programming",
    "topicSlug": "programming",
    "difficulty": "MEDIUM",
    "tags": ["javascript", "web"],
    "questionCount": 10,
    "plays": 1250,
    "questions": [
      {
        "id": "q_1",
        "text": "What is the typeof null in JavaScript?",
        "type": "MULTIPLE_CHOICE",
        "difficulty": "MEDIUM",
        "explanation": "typeof null returns 'object' due to a legacy bug.",
        "order": 1,
        "answers": [
          { "id": "a_1", "text": "null", "isCorrect": false },
          { "id": "a_2", "text": "object", "isCorrect": true },
          { "id": "a_3", "text": "undefined", "isCorrect": false }
        ]
      }
    ]
  }
}
```

--------------------------------

### GET /api/v1/questions

Source: https://quizapi.io/docs/questions

Returns all questions for a specific quiz in order. Pass a quiz_id to retrieve the ordered list of questions belonging to that quiz.

```APIDOC
## GET /api/v1/questions

### Description
Returns all questions for a specific quiz in order. Each question includes the parent quiz category.

### Method
GET

### Endpoint
/api/v1/questions

### Parameters
#### Query Parameters
- **quiz_id** (string) - Required - The ID of the quiz to fetch questions for
- **include_answers** (string) - Optional - Set to "true" to include the answers array with each question

### Request Example
curl -X GET "https://quizapi.io/api/v1/questions?quiz_id=quiz_abc123&include_answers=true" -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (array) - List of question objects
- **meta** (object) - Metadata including total count and quizId

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "ques_xyz789",
      "quizId": "quiz_abc123",
      "text": "What is the typeof null in JavaScript?",
      "type": "MULTIPLE_CHOICE",
      "difficulty": "MEDIUM",
      "explanation": "typeof null returns 'object' due to a legacy bug.",
      "category": "Programming",
      "answers": [
        { "id": "ans_1", "text": "null", "isCorrect": false },
        { "id": "ans_2", "text": "object", "isCorrect": true },
        { "id": "ans_3", "text": "undefined", "isCorrect": false },
        { "id": "ans_4", "text": "string", "isCorrect": false }
      ]
    }
  ],
  "meta": {
    "total": 10,
    "quizId": "quiz_abc123"
  }
}
```

--------------------------------

### GET /api/v1/quizzes

Source: https://quizapi.io/docs/playground

Retrieves a list of quizzes based on optional filters such as category, difficulty, tags, topic, sort order, limit, and offset.

```APIDOC
## GET /api/v1/quizzes

### Description
Retrieves a list of quizzes from the platform. Users can filter results by category, difficulty, tags, or topic, and control pagination using limit and offset.

### Method
GET

### Endpoint
/api/v1/quizzes

### Parameters
#### Query Parameters
- **Category** (string) - Optional - Filter quizzes by category
- **Difficulty** (string) - Optional - Filter quizzes by difficulty level
- **Tags** (string) - Optional - Filter quizzes by tags
- **Topic** (string) - Optional - Filter quizzes by topic
- **Sort** (string) - Optional - Sort order for the results
- **Limit** (integer) - Optional - Maximum number of results to return
- **Offset** (integer) - Optional - Number of results to skip
```

--------------------------------

### GET /api/v1/categories

Source: https://quizapi.io/docs/categories

Retrieves the full Topic to Category hierarchy, including quiz counts and popular tags for each category. This is a public endpoint and does not require authentication.

```APIDOC
## GET /api/v1/categories

### Description
Returns the full Topic to Category hierarchy with quiz counts and popular tags per category. This is a public discovery endpoint.

### Method
GET

### Endpoint
/api/v1/categories

### Response
#### Success Response (200)
- **id** (string) - Unique topic identifier
- **name** (string) - Display name
- **slug** (string) - URL-friendly slug
- **icon** (string | null) - Optional icon identifier
- **categories** (array) - List of categories within this topic
- **categories[].id** (string) - Category ID
- **categories[].name** (string) - Display name
- **categories[].slug** (string) - URL-friendly slug
- **categories[].quizCount** (number) - Number of published quizzes in this category
- **categories[].tags** (string[]) - Popular tags used across quizzes in this category

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "topic_abc123",
      "name": "Programming",
      "slug": "programming",
      "icon": "code",
      "categories": [
        {
          "id": "cat_python",
          "name": "Python",
          "slug": "python",
          "quizCount": 12,
          "tags": ["python", "basics", "data-structures", "oop"]
        }
      ]
    }
  ]
}
```

--------------------------------

### Expose Local Server with ngrok

Source: https://quizapi.io/docs/webhooks

Use ngrok to create a public URL for your local development server to receive webhook events.

```bash
# 1. Install ngrok
brew install ngrok    # macOS
# or download from https://ngrok.com

# 2. Start your local server
node server.js        # Starts on port 3000

# 3. Expose your local server to the internet
ngrok http 3000

# 4. Copy the ngrok URL (e.g., https://abc123.ngrok.io)
#    and set it as your webhook URL in the QuizAPI dashboard:
#    https://abc123.ngrok.io/webhooks/quizapi
```

--------------------------------

### Create a New Quiz

Source: https://quizapi.io/docs/quizzes

Submit a POST request to create a new quiz. Requires a Starter or Pro plan.

```bash
curl -X POST "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React Hooks Quiz",
    "description": "Test your knowledge of React hooks",
    "category": "Programming",
    "difficulty": "MEDIUM",
    "tags": ["react", "hooks"],
    "published": true,
    "featured": false
  }'
```

--------------------------------

### Authenticate with Query Parameter

Source: https://quizapi.io/docs/authentication

Pass the API key directly in the URL. This method is suitable for quick testing but discouraged for production due to potential logging of the key.

```bash
curl -X GET "https://quizapi.io/api/v1/quizzes?api_key=qza_live_abc123def456"
```

--------------------------------

### Fetch Quizzes via cURL

Source: https://quizapi.io/docs

Use this command to retrieve a list of quizzes. Ensure the Authorization header is populated with a valid API key.

```bash
curl -X GET "https://quizapi.io/api/v1/quizzes?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

--------------------------------

### POST /api/v1/quizzes

Source: https://quizapi.io/docs/quizzes

Creates a new quiz. Requires a Starter or Pro plan (admins are exempt).

```APIDOC
## POST /api/v1/quizzes

### Description
Creates a new quiz. Requires a Starter or Pro plan (admins are exempt). Quiz creation limits are enforced per plan. Admins can set featured to display the quiz in the Practice section.

### Method
POST

### Endpoint
https://quizapi.io/api/v1/quizzes

### Parameters
#### Request Body
- **title** (string) - Required - Title of the quiz (max 200 characters)
- **difficulty** (string) - Required - One of EASY, MEDIUM, HARD, or EXPERT
- **description** (string) - Optional - Description of the quiz (max 2000 characters)
- **category** (string) - Optional - Category name (flat string, max 100 characters)
- **categoryId** (string) - Optional - Category ID (preferred over flat category string)
- **tags** (string[]) - Optional - Array of tags (max 20 tags, 50 chars each)
- **published** (boolean) - Optional - Whether the quiz is publicly visible. Defaults to false
- **featured** (boolean) - Optional - Admin-only. Featured quizzes appear in the Practice section.

### Request Example
curl -X POST "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React Hooks Quiz",
    "description": "Test your knowledge of React hooks",
    "category": "Programming",
    "difficulty": "MEDIUM",
    "tags": ["react", "hooks"],
    "published": true,
    "featured": false
  }'

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - The created quiz object

#### Response Example
{
  "success": true,
  "data": {
    "id": "quiz_new789",
    "title": "React Hooks Quiz",
    "description": "Test your knowledge of React hooks",
    "category": "Programming",
    "categoryId": null,
    "difficulty": "MEDIUM",
    "tags": ["react", "hooks"],
    "published": true,
    "featured": false
  }
}
```

--------------------------------

### Handling Rate Limits in JavaScript

Source: https://quizapi.io/docs/rate-limits

Basic implementation for checking the 429 status code and reading the Retry-After header.

```javascript
// Check if you've been rate limited by inspecting the status code
const response = await fetch("https://quizapi.io/api/v1/quizzes", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
});

if (response.status === 429) {
  const retryAfter = response.headers.get("Retry-After") || "60";
  console.log(`Rate limited. Retry after ${retryAfter} seconds.`);
} else {
  const data = await response.json();
  console.log("Quizzes:", data.data);
}
```

--------------------------------

### Listen for QuizAPI Events

Source: https://quizapi.io/docs/embeds

Use window event listeners to react to quiz lifecycle events like initialization, completion, and answer submissions.

```html
<div id="quizapi-embed" data-quiz-id="quiz_abc123"></div>

<script src="https://quizapi.io/embed.js"></script>
<script>
  // Wait for the embed to initialize
  window.addEventListener("quizapi:ready", function () {
    console.log("Quiz embed is ready");
  });

  // Listen for quiz completion
  window.addEventListener("quizapi:complete", function (event) {
    const { quizId, score, totalQuestions, timeSpent } = event.detail;
    console.log("Quiz completed!", {
      quizId,
      score,
      totalQuestions,
      timeSpent,
    });

    // Example: send results to your analytics
    analytics.track("quiz_completed", event.detail);
  });

  // Listen for individual answer submissions
  window.addEventListener("quizapi:answer", function (event) {
    const { questionId, selectedAnswer, isCorrect } = event.detail;
    console.log("Answer submitted:", {
      questionId,
      selectedAnswer,
      isCorrect,
    });
  });
</script>
```

--------------------------------

### Batch Import Questions Request

Source: https://quizapi.io/docs/questions

Use this cURL command to send a POST request to the batch import endpoint. Ensure the Authorization header includes a valid API key.

```bash
curl -X POST "https://quizapi.io/api/v1/quizzes/quiz_abc123/questions/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [
      {
        "text": "What is a closure in JavaScript?",
        "type": "MULTIPLE_CHOICE",
        "difficulty": "MEDIUM",
        "explanation": "A closure is a function that retains access to its outer scope.",
        "answers": [
          { "text": "A function with access to outer scope variables", "isCorrect": true },
          { "text": "A way to close a browser window", "isCorrect": false },
          { "text": "A CSS layout technique", "isCorrect": false },
          { "text": "A type of HTML element", "isCorrect": false }
        ]
      }
    ]
  }'
```

--------------------------------

### Batch Import Questions Response

Source: https://quizapi.io/docs/questions

The API returns a success status and the details of the created questions, including their assigned IDs and order.

```json
{
  "success": true,
  "data": {
    "quizId": "quiz_abc123",
    "questionsCreated": 1,
    "questions": [
      {
        "id": "ques_new789",
        "text": "What is a closure in JavaScript?",
        "type": "MULTIPLE_CHOICE",
        "difficulty": "MEDIUM",
        "order": 11,
        "explanation": "A closure is a function that retains access to its outer scope.",
        "answers": [
          { "id": "ans_a1", "text": "A function with access to outer scope variables", "isCorrect": true },
          { "id": "ans_a2", "text": "A way to close a browser window", "isCorrect": false },
          { "id": "ans_a3", "text": "A CSS layout technique", "isCorrect": false },
          { "id": "ans_a4", "text": "A type of HTML element", "isCorrect": false }
        ]
      }
    ]
  }
}
```

--------------------------------

### POST /api/v1/quizzes/{quizId}/questions/batch

Source: https://quizapi.io/docs/questions

Imports a batch of questions into a specified quiz. The operation is atomic, meaning if any question fails validation, the entire batch is rejected.

```APIDOC
## POST /api/v1/quizzes/{quizId}/questions/batch

### Description
Import up to 50 questions into an existing quiz in a single request. Questions are validated and inserted atomically.

### Method
POST

### Endpoint
/api/v1/quizzes/{quizId}/questions/batch

### Parameters
#### Path Parameters
- **quizId** (string) - Required - The ID of the quiz to which questions will be added.

#### Request Body
- **questions** (array) - Required - Array of question objects (1–50 items).
- **questions[].text** (string) - Required - The question text.
- **questions[].type** (string) - Required - One of MULTIPLE_CHOICE, TRUE_FALSE, or OPEN_ENDED.
- **questions[].difficulty** (string) - Required - One of EASY, MEDIUM, HARD, or EXPERT.
- **questions[].explanation** (string) - Optional - Explanation shown after answering.
- **questions[].answers** (array) - Required - Array of answer objects (min 2). Each has text (string) and isCorrect (boolean).

### Request Example
{
  "questions": [
    {
      "text": "What is a closure in JavaScript?",
      "type": "MULTIPLE_CHOICE",
      "difficulty": "MEDIUM",
      "explanation": "A closure is a function that retains access to its outer scope.",
      "answers": [
        { "text": "A function with access to outer scope variables", "isCorrect": true },
        { "text": "A way to close a browser window", "isCorrect": false }
      ]
    }
  ]
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the quizId, count of questionsCreated, and the list of created questions.

#### Response Example
{
  "success": true,
  "data": {
    "quizId": "quiz_abc123",
    "questionsCreated": 1,
    "questions": [
      {
        "id": "ques_new789",
        "text": "What is a closure in JavaScript?",
        "type": "MULTIPLE_CHOICE",
        "difficulty": "MEDIUM",
        "order": 11,
        "explanation": "A closure is a function that retains access to its outer scope.",
        "answers": [
          { "id": "ans_a1", "text": "A function with access to outer scope variables", "isCorrect": true },
          { "id": "ans_a2", "text": "A way to close a browser window", "isCorrect": false }
        ]
      }
    ]
  }
}
```

--------------------------------

### Fetch Quiz Questions via cURL

Source: https://quizapi.io/docs/questions

Retrieve an ordered list of questions for a specific quiz by providing the quiz_id and an optional flag to include answer details.

```bash
curl -X GET "https://quizapi.io/api/v1/questions?quiz_id=quiz_abc123&include_answers=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### List Quizzes Request

Source: https://quizapi.io/docs/quizzes

Retrieve a paginated list of quizzes using cURL with optional query parameters for filtering and sorting.

```bash
curl -X GET "https://quizapi.io/api/v1/quizzes?topicSlug=programming&sort=newest&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Retrieve a Quiz by ID

Source: https://quizapi.io/docs/quizzes

Use this request to fetch a specific quiz including its questions and metadata.

```bash
curl -X GET "https://quizapi.io/api/v1/quizzes/quiz_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Interact with QuizAPI via REST

Source: https://quizapi.io/docs/sdks

Use standard curl commands to perform CRUD operations on quizzes. Ensure your API key is included in the Authorization header.

```bash
# List quizzes
curl -X GET "https://quizapi.io/api/v1/quizzes?category=programming&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a single quiz
curl -X GET "https://quizapi.io/api/v1/quizzes/quiz_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a quiz
curl -X POST "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React Hooks Quiz",
    "category": "programming",
    "difficulty": "MEDIUM"
  }'
```

--------------------------------

### Create a Quiz with Category ID

Source: https://quizapi.io/docs/categories

Use a category ID obtained from the categories endpoint when creating a new quiz. Requires an API key in the Authorization header.

```bash
# 1. Get the Python category ID from /api/v1/categories
# 2. Use it when creating a quiz:

curl -X POST "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Python Decorators",
    "description": "Test your knowledge of Python decorators",
    "categoryId": "cat_python",
    "difficulty": "HARD",
    "tags": ["python", "decorators", "oop"],
    "published": true
  }'
```

--------------------------------

### Authenticate with Authorization Header

Source: https://quizapi.io/docs/authentication

The recommended, secure method for passing API keys as a Bearer token in the request header.

```bash
curl -X GET "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer qza_live_abc123def456"
```

--------------------------------

### Configure Embedded Quiz with Options

Source: https://quizapi.io/docs/embeds

Customize the quiz appearance and behavior by adding data attributes to the container element.

```html
<div
  id="quizapi-embed"
  data-quiz-id="quiz_abc123"
  data-theme="dark"
  data-color="#6366f1"
  data-show-leaderboard="true"
></div>

<script src="https://quizapi.io/embed.js"></script>
```

--------------------------------

### Quiz Creation Response

Source: https://quizapi.io/docs/quizzes

The JSON structure returned upon successful creation of a new quiz.

```json
{
  "success": true,
  "data": {
    "id": "quiz_new789",
    "title": "React Hooks Quiz",
    "description": "Test your knowledge of React hooks",
    "category": "Programming",
    "categoryId": null,
    "difficulty": "MEDIUM",
    "tags": ["react", "hooks"],
    "published": true,
    "featured": false
  }
}
```

--------------------------------

### Query Parameter

Source: https://quizapi.io/docs/authentication

An alternative method for authenticating requests by passing the API key as a query parameter. Useful for quick testing.

```APIDOC
## Query Parameter

### Description
Pass the API key as a query parameter named `api_key`. Note that this is not recommended for production as the key may appear in server logs.

### Query Parameters
- **api_key** (string) - Required - Your production or test API key.

### Request Example
curl -X GET "https://quizapi.io/api/v1/quizzes?api_key=qza_live_abc123def456"
```

--------------------------------

### Authorization Header

Source: https://quizapi.io/docs/authentication

The recommended method for authenticating requests by passing the API key as a Bearer token in the Authorization header.

```APIDOC
## Authorization Header

### Description
Pass your API key in the `Authorization` header as a Bearer token. This is the recommended and most secure method for production use.

### Request Example
curl -X GET "https://quizapi.io/api/v1/quizzes" \
  -H "Authorization: Bearer qza_live_abc123def456"
```

--------------------------------

### Handle Authentication Errors

Source: https://quizapi.io/docs/authentication

The JSON response structure returned by the API when authentication fails.

```json
{
  "success": false,
  "error": "Invalid API key."
}
```

--------------------------------

### Embed Quiz via Script Tag

Source: https://quizapi.io/docs/embeds

The standard method for rendering a quiz directly into the page, enabling JavaScript API access and custom styling.

```html
<!-- Add this where you want the quiz to appear -->
<div id="quizapi-embed" data-quiz-id="QUIZ_ID"></div>

<!-- Include the QuizAPI embed script -->
<script src="https://quizapi.io/embed.js"></script>
```

--------------------------------

### Webhook Request Header

Source: https://quizapi.io/docs/webhooks

The standard HTTP POST request structure for incoming webhook notifications.

```http
POST /webhooks/quizapi HTTP/1.1
```

--------------------------------

### Webhook Payload Structure

Source: https://quizapi.io/docs/webhooks

Describes the standard JSON payload format sent to your configured webhook URL.

```APIDOC
## POST /webhooks/quizapi

### Description
Receives real-time event notifications from QuizAPI. The payload is a JSON object delivered via HTTP POST.

### Method
POST

### Request Body
- **id** (string) - Unique event identifier
- **event** (string) - The type of event (e.g., quiz.completed, quiz.created)
- **created_at** (string) - ISO 8601 timestamp of the event
- **data** (object) - Event-specific data payload

### Response
#### Success Response (200)
- The server should return a 200 OK status to acknowledge receipt of the webhook.
```

--------------------------------

### Exponential Backoff Utility

Source: https://quizapi.io/docs/rate-limits

A JavaScript function that implements exponential backoff with jitter to handle 429 responses automatically.

```javascript
async function fetchWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // Get the retry delay from the Retry-After header
    const retryAfter = parseInt(
      response.headers.get("Retry-After") || "1",
      10
    );

    // Use exponential backoff with jitter
    const delay = retryAfter * 1000 + Math.random() * 1000;

    console.log(
      `Rate limited. Retrying in ${Math.round(delay / 1000)}s ` +
      `(attempt ${attempt + 1}/${maxRetries})`
    );

    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Max retries exceeded");
}
```

--------------------------------

### Override embed styles with CSS custom properties

Source: https://quizapi.io/docs/embeds

Apply these variables to the #quizapi-embed container to customize the visual theme of the quiz.

```css
/* Override embed styles with CSS custom properties */
#quizapi-embed {
  --quizapi-font-family: "Inter", sans-serif;
  --quizapi-border-radius: 12px;
  --quizapi-primary-color: #6366f1;
  --quizapi-background: #ffffff;
  --quizapi-text-color: #1f2937;
  --quizapi-border-color: #e5e7eb;
  --quizapi-correct-color: #22c55e;
  --quizapi-incorrect-color: #ef4444;
}
```

--------------------------------

### Quiz Retrieval Response

Source: https://quizapi.io/docs/quizzes

The JSON structure returned when successfully fetching a quiz.

```json
{
  "success": true,
  "data": {
    "id": "quiz_abc123",
    "title": "JavaScript Fundamentals",
    "slug": "javascript-fundamentals",
    "description": "Test your knowledge of JS basics",
    "category": "Programming",
    "categoryId": "cat_javascript",
    "categoryName": "JavaScript",
    "categorySlug": "javascript",
    "topic": "Programming",
    "topicSlug": "programming",
    "difficulty": "MEDIUM",
    "tags": ["javascript", "web"],
    "questionCount": 10,
    "plays": 1250,
    "questions": [
      {
        "id": "q_1",
        "text": "What is the typeof null in JavaScript?",
        "type": "MULTIPLE_CHOICE",
        "difficulty": "MEDIUM",
        "explanation": "typeof null returns 'object' due to a legacy bug.",
        "order": 1,
        "answers": [
          { "id": "a_1", "text": "null", "isCorrect": false },
          { "id": "a_2", "text": "object", "isCorrect": true },
          { "id": "a_3", "text": "undefined", "isCorrect": false }
        ]
      }
    ]
  }
}
```

--------------------------------

### Categories API Response Structure

Source: https://quizapi.io/docs/categories

The JSON response contains a list of topics, each including nested categories with quiz counts and popular tags.

```json
{
  "success": true,
  "data": [
    {
      "id": "topic_abc123",
      "name": "Programming",
      "slug": "programming",
      "icon": "code",
      "categories": [
        {
          "id": "cat_python",
          "name": "Python",
          "slug": "python",
          "quizCount": 12,
          "tags": ["python", "basics", "data-structures", "oop"]
        },
        {
          "id": "cat_javascript",
          "name": "JavaScript",
          "slug": "javascript",
          "quizCount": 8,
          "tags": ["javascript", "react", "typescript", "node"]
        }
      ]
    },
    {
      "id": "topic_def456",
      "name": "DevOps & Cloud",
      "slug": "devops-cloud",
      "icon": null,
      "categories": [
        {
          "id": "cat_docker",
          "name": "Docker",
          "slug": "docker",
          "quizCount": 3,
          "tags": ["docker", "containers", "devops"]
        }
      ]
    }
  ]
}
```

--------------------------------

### Script Tag Embed

Source: https://quizapi.io/docs/embeds

The script tag method renders the quiz directly in your page, allowing for JavaScript event handling and custom styling.

```APIDOC
## Script Tag Embed

### Description
Embeds a quiz directly into the page using a container div and the QuizAPI script.

### Implementation
```html
<!-- Add this where you want the quiz to appear -->
<div id="quizapi-embed" data-quiz-id="QUIZ_ID"></div>

<!-- Include the QuizAPI embed script -->
<script src="https://quizapi.io/embed.js"></script>
```

### Configuration Options
- **data-quiz-id** (string) - Required - The unique ID of the quiz to embed
- **data-theme** (string) - Optional - Color theme: 'light', 'dark', or 'auto' (default: 'auto')
- **data-color** (string) - Optional - Accent color as a hex value (default: '#6366f1')
- **data-show-leaderboard** (boolean) - Optional - Whether to show the leaderboard after quiz completion (default: false)
```

--------------------------------

### JavaScript Embed Events

Source: https://quizapi.io/docs/embeds

The embed dispatches custom events on the window object. You can listen for these events to react to user interactions within the quiz.

```APIDOC
## JavaScript Embed Events

### Description
The QuizAPI embed dispatches custom events on the `window` object. Use these events to react to quiz interactions in your application.

### Events
- **quizapi:ready** - Fired when the embed has fully loaded and is ready.
- **quizapi:complete** - Fired when the user finishes the quiz. Payload: `quizId`, `score`, `totalQuestions`, `timeSpent`.
- **quizapi:answer** - Fired each time the user submits an answer. Payload: `questionId`, `selectedAnswer`, `isCorrect`.

### Usage Example
```javascript
window.addEventListener("quizapi:complete", function (event) {
  const { quizId, score, totalQuestions, timeSpent } = event.detail;
  console.log("Quiz completed!", { quizId, score, totalQuestions, timeSpent });
});
```
```