Retrieve questions for quizzes or browse across all quizzes
openapi: 3.1.0
info:
title: Quiz Discovery Questions 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: Questions
description: Retrieve questions for quizzes or browse across all quizzes
paths:
/api/v1/questions:
get:
summary: Get questions
description: 'Two modes: (1) Pass `quiz_id` to get ordered questions for a specific quiz. (2) Omit `quiz_id` to browse questions across all published quizzes with pagination, filtering, and optional randomization. Only approved quizzes and your own quizzes are included.'
tags:
- Questions
security:
- BearerAuth: []
parameters:
- schema:
type: string
description: If provided, returns questions for this quiz (Mode 1). If omitted, enters browse mode (Mode 2).
example: cm3abc123def456
required: false
description: If provided, returns questions for this quiz (Mode 1). If omitted, enters browse mode (Mode 2).
name: quiz_id
in: query
- schema:
type: string
description: Set to "true" to include answers (Mode 1 only). In browse mode, answers are always included.
example: 'true'
required: false
description: Set to "true" to include answers (Mode 1 only). In browse mode, answers are always included.
name: include_answers
in: query
- schema:
type: string
description: Filter by quiz category. Supports comma-separated values for multiple categories (case-insensitive). Browse mode only.
example: Programming,DevOps
required: false
description: Filter by quiz category. Supports comma-separated values for multiple categories (case-insensitive). Browse mode only.
name: category
in: query
- schema:
type: string
description: Filter by difficulty. Supports comma-separated values (case-insensitive). Browse mode only.
example: EASY,MEDIUM
required: false
description: Filter by difficulty. Supports comma-separated values (case-insensitive). Browse mode only.
name: difficulty
in: query
- schema:
type: string
description: Filter by question type. Supports comma-separated values. Browse mode only.
example: MULTIPLE_CHOICE,TRUE_FALSE
required: false
description: Filter by question type. Supports comma-separated values. Browse mode only.
name: type
in: query
- schema:
type: string
description: Comma-separated tags to match (browse mode only)
example: javascript,react
required: false
description: Comma-separated tags to match (browse mode only)
name: tags
in: query
- schema:
type: integer
minimum: 1
maximum: 50
default: 10
description: Max questions to return per page in browse mode (1–50)
required: false
description: Max questions to return per page in browse mode (1–50)
name: limit
in: query
- schema:
type:
- integer
- 'null'
minimum: 0
default: 0
description: Number of questions to skip for pagination (browse mode only)
required: false
description: Number of questions to skip for pagination (browse mode only)
name: offset
in: query
- schema:
type: string
description: Set to "true" to shuffle the returned questions randomly (browse mode only)
example: 'true'
required: false
description: Set to "true" to shuffle the returned questions randomly (browse mode only)
name: random
in: query
responses:
'200':
description: Questions retrieved successfully
content:
application/json:
schema:
anyOf:
- type: object
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
$ref: '#/components/schemas/QuizQuestion'
meta:
type: object
properties:
total:
type: integer
quizId:
type: string
required:
- total
- quizId
required:
- success
- data
- meta
description: Mode 1 response (quiz_id provided)
- type: object
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
$ref: '#/components/schemas/BrowseQuestion'
meta:
$ref: '#/components/schemas/PaginationMeta'
required:
- success
- data
- meta
description: Mode 2 response (browse mode)
'400':
description: Invalid parameters (e.g. bad difficulty or type value)
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'
/api/v1/quizzes/{id}/questions/batch:
post:
summary: Batch import questions
description: Import multiple questions into an existing quiz at once. Validates all questions before inserting — if any fail validation, the entire batch is rejected. Questions are appended after existing questions. **Requires a paid plan (Starter or Pro) or admin role.**
tags:
- Questions
security:
- BearerAuth: []
parameters:
- schema:
type: string
description: The quiz ID to add questions to
example: cm3abc123def456
required: true
description: The quiz ID to add questions to
name: id
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
questions:
type: array
items:
$ref: '#/components/schemas/BatchQuestionInput'
minItems: 1
maxItems: 50
description: Array of questions to import (1–50)
required:
- questions
responses:
'201':
description: Questions created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchImportResponse'
'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: Forbidden — free plan users cannot use batch import, or quiz is not owned by API key holder
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Quiz not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation failed — one or more questions have errors
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
error:
type: string
details:
type: array
items: {}
required:
- success
- error
'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:
BrowseQuestion:
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.
category:
type:
- string
- 'null'
example: Programming
tags:
type: array
items:
type: string
example:
- javascript
- fundamentals
quizId:
type: string
example: cm3abc123def456
quizTitle:
type: string
example: JavaScript Essentials
answers:
type: array
items:
$ref: '#/components/schemas/Answer'
required:
- id
- text
- type
- difficulty
- explanation
- category
- tags
- quizId
- quizTitle
- answers
description: A question with quiz context (returned in browse mode)
PaginationMeta:
type: object
properties:
total:
type: integer
description: Total matching results across all pages
example: 23
pageTotal:
type: integer
description: Number of results in this page
example: 10
page:
type: integer
description: Current page number (1-based)
example: 1
lastPage:
type: integer
description: Total number of pages
example: 3
limit:
type: integer
description: Results per page
example: 10
offset:
type: integer
description: Number of results skipped
example: 0
links:
$ref: '#/components/schemas/PaginationLinks'
required:
- total
- pageTotal
- page
- lastPage
- limit
- offset
- links
description: Pagination metadata included in browse responses
BatchQuestionInput:
type: object
properties:
text:
type: string
example: What is the typeof null in JavaScript?
type:
$ref: '#/components/schemas/QuestionType'
difficulty:
$ref: '#/components/schemas/Difficulty'
explanation:
type: string
example: typeof null returns 'object' due to a legacy bug in JavaScript.
answers:
type: array
items:
type: object
properties:
text:
type: string
example: object
isCorrect:
type: boolean
example: true
required:
- text
- isCorrect
minItems: 2
description: At least 2 answers required. TRUE_FALSE must have exactly 2.
required:
- text
- type
- difficulty
- answers
description: A question to create in the batch
Difficulty:
type: string
enum:
- EASY
- MEDIUM
- HARD
- EXPERT
description: Difficulty level of a quiz or question
ErrorResponse:
type: object
properties:
success:
type: boolean
enum:
- false
error:
type: string
example: Something went wrong.
required:
- success
- error
description: Standard error response
QuizQuestion:
type: object
properties:
id:
type: string
example: cm3xyz789ghi012
quizId:
type: string
example: cm3abc123def456
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.
category:
type:
- string
- 'null'
example: Programming
description: Category of the parent quiz
answers:
type: array
items:
$ref: '#/components/schemas/Answer'
description: Included when include_answers=true
required:
- id
- quizId
- text
- type
- difficulty
- explanation
- category
description: A question belonging to a specific quiz (returned with quiz_id mode)
PaginationLinks:
type: object
properties:
first:
type: string
example: /api/v1/questions?offset=0&limit=10
last:
type: string
example: /api/v1/questions?offset=20&limit=10
next:
type:
- string
- 'null'
example: /api/v1/questions?offset=10&limit=10
prev:
type:
- string
- 'null'
example: null
required:
- first
- last
- next
- prev
description: Navigation links for pagination
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
BatchImportResponse:
type: object
properties:
success:
type: boolean
enum:
- true
data:
type: object
properties:
quizId:
type: string
example: cm3abc123def456
questionsCreated:
type: integer
example: 5
questions:
type: array
items:
$ref: '#/components/schemas/QuizQuestionDetail'
required:
- quizId
- questionsCreated
- questions
required:
- success
- data
description: Successful batch import response
QuestionType:
type: string
enum:
- MULTIPLE_CHOICE
- TRUE_FALSE
- OPEN_ENDED
description: The type of question
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.'