openapi: 3.1.0
info:
  title: Quiz Discovery Quizzes API
  version: 1.0.0
  description: Access thousands of quiz questions across programming, science, and more. Browse by category, difficulty, and tags.
  contact:
    name: QuizAPI Support
    url: https://quizapi.io
servers:
- url: https://quizapi.io
  description: Production
security: []
tags:
- name: Quizzes
  description: Browse and search published quizzes
paths:
  /api/v1/quizzes:
    get:
      summary: List quizzes
      description: Returns a paginated list of published, approved quizzes (plus your own). Supports filtering by category, difficulty, tags, and free-text topic search.
      tags:
      - Quizzes
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: Filter by category (case-insensitive)
          example: Programming
        required: false
        description: Filter by category (case-insensitive)
        name: category
        in: query
      - schema:
          allOf:
          - $ref: '#/components/schemas/Difficulty'
          - description: Filter by difficulty level
        required: false
        description: Filter by difficulty level
        name: difficulty
        in: query
      - schema:
          type: string
          description: Comma-separated list of tags
          example: javascript,react
        required: false
        description: Comma-separated list of tags
        name: tags
        in: query
      - schema:
          type: string
          description: Free-text search in title, description, and tags
          example: react hooks
        required: false
        description: Free-text search in title, description, and tags
        name: topic
        in: query
      - schema:
          type: string
          enum:
          - popular
          - newest
          - title
          default: popular
          description: 'Sort order: popular (plays desc), newest (created desc), or title (alphabetical asc)'
          example: popular
        required: false
        description: 'Sort order: popular (plays desc), newest (created desc), or title (alphabetical asc)'
        name: sort
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: Number of results to return (1–50)
        required: false
        description: Number of results to return (1–50)
        name: limit
        in: query
      - schema:
          type:
          - integer
          - 'null'
          minimum: 0
          default: 0
          description: Number of results to skip for pagination
        required: false
        description: Number of results to skip for pagination
        name: offset
        in: query
      responses:
        '200':
          description: Quizzes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/QuizListItem'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
                    required:
                    - total
                    - limit
                    - offset
                required:
                - success
                - data
                - meta
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create a quiz
      description: 'Create a new quiz. Requires a Starter or Pro plan (admins are exempt). Quiz creation limits are enforced per plan. Admins can set `featured: true` to display the quiz in the Practice section immediately. Non-admin users can add `featured` in the body but it will be silently ignored.'
      tags:
      - Quizzes
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuizRequest'
      responses:
        '201':
          description: Quiz created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/CreatedQuiz'
                required:
                - success
                - data
        '400':
          description: Invalid JSON body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Free plan (upgrade required) or quiz limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/quizzes/{id}:
    get:
      summary: Get a single quiz
      description: Returns full details for a single quiz including all questions and answers. Only published quizzes that are approved or owned by the API key holder are returned.
      tags:
      - Quizzes
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: The quiz ID
          example: cm3abc123def456
        required: true
        description: The quiz ID
        name: id
        in: path
      responses:
        '200':
          description: Quiz retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/QuizDetail'
                required:
                - success
                - data
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Quiz not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    QuizDetail:
      type: object
      properties:
        id:
          type: string
          example: cm3abc123def456
        title:
          type: string
          example: JavaScript Fundamentals
        description:
          type: string
          example: Test your JS knowledge
        category:
          type: string
          example: Programming
        difficulty:
          $ref: '#/components/schemas/Difficulty'
        tags:
          type: array
          items:
            type: string
          example:
          - javascript
          - web
        questionCount:
          type: integer
          example: 10
        plays:
          type: integer
          example: 1250
        slug:
          type: string
          example: javascript-fundamentals
        questions:
          type: array
          items:
            $ref: '#/components/schemas/QuizQuestionDetail'
      required:
      - id
      - title
      - description
      - category
      - difficulty
      - tags
      - questionCount
      - plays
      - slug
      - questions
      description: Full quiz details including questions and answers
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
          example: Something went wrong.
      required:
      - success
      - error
      description: Standard error response
    QuizListItem:
      type: object
      properties:
        id:
          type: string
          example: cm3abc123def456
        title:
          type: string
          example: JavaScript Fundamentals
        description:
          type: string
          example: Test your JS knowledge
        category:
          type: string
          example: Programming
        difficulty:
          $ref: '#/components/schemas/Difficulty'
        tags:
          type: array
          items:
            type: string
          example:
          - javascript
          - web
        questionCount:
          type: integer
          example: 10
        plays:
          type: integer
          example: 1250
        slug:
          type: string
          example: javascript-fundamentals
      required:
      - id
      - title
      - description
      - category
      - difficulty
      - tags
      - questionCount
      - plays
      - slug
      description: A quiz summary returned in list endpoints
    CreateQuizRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          example: Python Basics
        description:
          type: string
          maxLength: 2000
          example: Learn Python fundamentals.
        category:
          type: string
          maxLength: 100
          example: Programming
        categoryId:
          type: string
          description: Category ID (preferred over flat category string)
          example: cat_python
        difficulty:
          $ref: '#/components/schemas/Difficulty'
        tags:
          type: array
          items:
            type: string
            maxLength: 50
          maxItems: 20
          example:
          - python
          - basics
        published:
          type: boolean
          default: false
          description: Whether the quiz is publicly visible
        featured:
          type: boolean
          default: false
          description: Admin-only. Mark as featured in the Practice section. Ignored for non-admin users.
      required:
      - title
      - difficulty
      description: Request body for creating a quiz via the API
    QuizQuestionDetail:
      type: object
      properties:
        id:
          type: string
          example: cm3xyz789ghi012
        text:
          type: string
          example: What is the typeof null in JavaScript?
        type:
          $ref: '#/components/schemas/QuestionType'
        difficulty:
          $ref: '#/components/schemas/Difficulty'
        explanation:
          type:
          - string
          - 'null'
          example: typeof null returns 'object' due to a legacy bug in JavaScript.
        order:
          type: integer
          example: 1
        answers:
          type: array
          items:
            $ref: '#/components/schemas/Answer'
      required:
      - id
      - text
      - type
      - difficulty
      - explanation
      - order
      - answers
      description: A question with answers, returned within a quiz detail
    Answer:
      type: object
      properties:
        id:
          type: string
          example: ans_abc123
        text:
          type: string
          example: '42'
        isCorrect:
          type: boolean
          example: true
      required:
      - id
      - text
      - isCorrect
      description: An answer option for a question
    Difficulty:
      type: string
      enum:
      - EASY
      - MEDIUM
      - HARD
      - EXPERT
      description: Difficulty level of a quiz or question
    QuestionType:
      type: string
      enum:
      - MULTIPLE_CHOICE
      - TRUE_FALSE
      - OPEN_ENDED
      description: The type of question
    CreatedQuiz:
      type: object
      properties:
        id:
          type: string
          example: cm3abc123def456
        title:
          type: string
          example: Python Basics
        description:
          type:
          - string
          - 'null'
          example: Learn Python fundamentals.
        category:
          type:
          - string
          - 'null'
          example: Programming
        categoryId:
          type:
          - string
          - 'null'
          example: cat_python
        difficulty:
          $ref: '#/components/schemas/Difficulty'
        tags:
          type: array
          items:
            type: string
          example:
          - python
          - basics
        published:
          type: boolean
          example: true
        featured:
          type: boolean
          example: false
      required:
      - id
      - title
      - description
      - category
      - categoryId
      - difficulty
      - tags
      - published
      - featured
      description: A newly created quiz
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as a Bearer token: `Authorization: Bearer qza_live_...`. Alternatively, use the `api_key` query parameter.'