API Reference

Quizzes API

Create, retrieve, update, and delete quizzes. The Quizzes API is the core of QuizAPI, giving you full control over your quiz content.

The Quiz Object

A quiz represents a collection of questions with associated metadata and settings.

Attribute	Type	Description
`id`	string	Unique identifier for the quiz (e.g., `quiz_abc123`)
`title`	string	The title of the quiz
`description`	string \| null	Optional description
`category`	string	Category slug (e.g., programming, science, math)
`difficulty`	string	One of: `EASY`, `MEDIUM`, `HARD`, `EXPERT`
`tags`	string[]	Array of tag strings for filtering
`questionCount`	integer	Number of questions in the quiz
`plays`	integer	Total number of times the quiz has been played

GET/api/v1/quizzes

List Quizzes

Returns a paginated list of quizzes. You can filter by category, difficulty, and tags.

Query Parameters

Parameter	Type	Default	Description
`category`	string	-	Filter by category (e.g., programming, science)
`difficulty`	string	-	Filter by difficulty: beginner, intermediate, advanced
`tags`	string	-	Comma-separated list of tags to filter by
`limit`	integer	20	Number of results to return (1-100)
`offset`	integer	0	Number of results to skip for pagination
`sort`	string	popular	Sort order: `popular` (most played), `newest`, or `title` (alphabetical)
`topic`	string	-	Free-text search across title, description, and tags

Example Request

bash

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

Example Response

json

{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "JavaScript Fundamentals",
      "slug": "javascript-fundamentals",
      "description": "Test your knowledge of JS basics",
      "category": "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",
      "difficulty": "EASY",
      "tags": ["python", "data-structures"],
      "questionCount": 15,
      "plays": 830
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

GET/api/v1/quizzes/:id

Get a Quiz

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

Path Parameters

Parameter	Type	Description
`id`	string	The quiz ID (e.g., `quiz_abc123`)

Example Request

bash

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

Example Response

json

{
  "success": true,
  "data": {
    "id": "quiz_abc123",
    "title": "JavaScript Fundamentals",
    "slug": "javascript-fundamentals",
    "description": "Test your knowledge of JS basics",
    "category": "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 }
        ]
      }
    ]
  }
}

POST/api/v1/quizzes

Create a Quiz

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.

Starter / Pro plan required20 requests/min rate limit

Request Body

Field	Type	Required	Description
`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. Silently ignored for non-admin users.

Example Request

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
  }'

Example Response

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

Response Format

All API responses follow a consistent format. Successful single-object responses wrap the result in a data key. List endpoints include a meta object for pagination.

Status Code	Description
200	Successful request
201	Resource created successfully
400	Bad request (validation error)
401	Unauthorized (missing or invalid API key)
404	Resource not found
429	Rate limit exceeded