openapi: 3.0.3 info: title: Open Trivia Database API version: '1.0' description: | The Open Trivia Database (OpenTDB) is a free, user-contributed trivia question database operated by Pixeltail Games LLC. This OpenAPI specification describes the public JSON REST API exposed at https://opentdb.com. The API supports five endpoints: - /api.php — retrieve a batch of trivia questions - /api_category.php — list all categories and their IDs - /api_count.php — get question counts per category broken down by difficulty - /api_count_global.php — return global database statistics - /api_token.php — request, reset, or recycle a session token All endpoints return JSON. The API enforces a documented rate limit of one request per IP every five seconds (HTTP 429). Questions are licensed under Creative Commons Attribution-ShareAlike 4.0 International. contact: name: Open Trivia Database (Pixeltail Games) url: https://opentdb.com/contact.php license: name: CC BY-SA 4.0 url: https://creativecommons.org/licenses/by-sa/4.0/ termsOfService: https://opentdb.com/terms.php x-generated-from: documentation x-last-validated: '2026-05-30' servers: - url: https://opentdb.com description: Open Trivia Database production endpoint tags: - name: Questions description: Operations for retrieving trivia questions from the database. - name: Categories description: Operations for discovering trivia category metadata and counts. - name: Statistics description: Operations for inspecting overall database statistics. - name: Tokens description: Operations for managing session tokens that prevent duplicate questions. paths: /api.php: get: operationId: getQuestions summary: Open Trivia Get Trivia Questions description: >- Retrieve a batch of trivia questions from the Open Trivia Database. Questions can be filtered by category, difficulty, and type. A session token may be supplied to prevent the same question from being returned twice within a six-hour window. tags: - Questions parameters: - name: amount in: query required: true description: >- Number of questions to return. Must be between 1 and 50 inclusive. schema: type: integer minimum: 1 maximum: 50 default: 10 example: 10 - name: category in: query required: false description: >- Numeric category identifier. Use /api_category.php to discover valid category IDs (range 9-32). Omit to draw from any category. schema: type: integer minimum: 9 maximum: 32 example: 9 - name: difficulty in: query required: false description: Restrict questions to a single difficulty level. schema: type: string enum: - easy - medium - hard example: medium - name: type in: query required: false description: >- Restrict questions to a single answer format. `multiple` returns four-option multiple-choice questions; `boolean` returns true/false questions. schema: type: string enum: - multiple - boolean example: multiple - name: encode in: query required: false description: >- Response encoding for textual fields. Defaults to HTML-entity encoded plain text. `urlLegacy` applies legacy URL encoding, `url3986` applies RFC 3986 percent encoding, and `base64` applies Base64 encoding. schema: type: string enum: - urlLegacy - url3986 - base64 example: base64 - name: token in: query required: false description: >- Session token returned by /api_token.php. When provided, the API tracks which questions have been served and avoids returning duplicates until the token is reset or expires. schema: type: string example: 5b76e266e1955dc8c216be34a8280d1f8e2d9f82d3d93a755f772d2537e14b25 responses: '200': description: A trivia question response envelope. content: application/json: schema: $ref: '#/components/schemas/QuestionResponse' examples: multipleChoiceBatch: summary: Two multiple-choice questions value: response_code: 0 results: - type: multiple difficulty: medium category: Science & Nature question: What is the chemical symbol for gold? correct_answer: Au incorrect_answers: - Ag - Go - Gd - type: boolean difficulty: easy category: General Knowledge question: The Pacific Ocean is the largest ocean on Earth. correct_answer: 'True' incorrect_answers: - 'False' noResults: summary: Not enough questions in the category to satisfy the request value: response_code: 1 results: [] '429': description: Rate limit exceeded (one request per IP every five seconds). content: application/json: schema: $ref: '#/components/schemas/ResponseEnvelope' examples: rateLimited: summary: Rate limit response value: response_code: 5 response_message: Rate Limit Exceeded x-microcks-operation: delay: 0 dispatcher: FALLBACK x-microcks-default: multipleChoiceBatch /api_category.php: get: operationId: getCategories summary: Open Trivia List Trivia Categories description: >- Return the full list of trivia categories supported by the Open Trivia Database, each with its numeric identifier and human-readable name. tags: - Categories responses: '200': description: The list of available trivia categories. content: application/json: schema: $ref: '#/components/schemas/CategoryListResponse' examples: allCategories: summary: Full category list value: trivia_categories: - id: 9 name: General Knowledge - id: 10 name: 'Entertainment: Books' - id: 11 name: 'Entertainment: Film' - id: 12 name: 'Entertainment: Music' - id: 17 name: Science & Nature - id: 18 name: 'Science: Computers' - id: 19 name: 'Science: Mathematics' - id: 21 name: Sports - id: 22 name: Geography - id: 23 name: History x-microcks-operation: delay: 0 dispatcher: FALLBACK x-microcks-default: allCategories /api_count.php: get: operationId: getCategoryCount summary: Open Trivia Get Category Question Count description: >- Return the number of questions available in a single category broken down by difficulty level (easy, medium, hard) plus the overall total. tags: - Categories parameters: - name: category in: query required: true description: >- Numeric category identifier. Use /api_category.php to discover valid category IDs (range 9-32). schema: type: integer minimum: 9 maximum: 32 example: 9 responses: '200': description: Question counts for the requested category. content: application/json: schema: $ref: '#/components/schemas/CategoryCountResponse' examples: generalKnowledge: summary: Counts for General Knowledge (category 9) value: category_id: 9 category_question_count: total_question_count: 469 total_easy_question_count: 215 total_medium_question_count: 177 total_hard_question_count: 77 x-microcks-operation: delay: 0 dispatcher: FALLBACK x-microcks-default: generalKnowledge /api_count_global.php: get: operationId: getGlobalCount summary: Open Trivia Get Global Question Count description: >- Return overall question counts for the Open Trivia Database — total questions, pending submissions, verified questions, and rejected submissions — both globally and per category. tags: - Statistics responses: '200': description: Global database statistics broken down per category. content: application/json: schema: $ref: '#/components/schemas/GlobalCountResponse' examples: globalStats: summary: Global statistics snapshot value: overall: total_num_of_questions: 21531 total_num_of_pending_questions: 10828 total_num_of_verified_questions: 5296 total_num_of_rejected_questions: 5424 categories: '9': total_num_of_questions: 469 total_num_of_pending_questions: 200 total_num_of_verified_questions: 215 total_num_of_rejected_questions: 54 '17': total_num_of_questions: 230 total_num_of_pending_questions: 110 total_num_of_verified_questions: 95 total_num_of_rejected_questions: 25 x-microcks-operation: delay: 0 dispatcher: FALLBACK x-microcks-default: globalStats /api_token.php: get: operationId: manageToken summary: Open Trivia Manage Session Token description: >- Request a new session token or reset an existing one. Session tokens prevent duplicate questions across calls and expire after six hours of inactivity. Use `command=request` to obtain a new token and `command=reset` with the token parameter to recycle an existing token's served-question set. tags: - Tokens parameters: - name: command in: query required: true description: The token operation to perform. schema: type: string enum: - request - reset example: request - name: token in: query required: false description: >- Existing session token. Required when `command=reset`; ignored when `command=request`. schema: type: string example: 5b76e266e1955dc8c216be34a8280d1f8e2d9f82d3d93a755f772d2537e14b25 responses: '200': description: The token response envelope. content: application/json: schema: $ref: '#/components/schemas/TokenResponse' examples: tokenIssued: summary: New token issued value: response_code: 0 response_message: Token Generated Successfully! token: 5b76e266e1955dc8c216be34a8280d1f8e2d9f82d3d93a755f772d2537e14b25 tokenReset: summary: Existing token recycled value: response_code: 0 response_message: Token Reset Success! token: 5b76e266e1955dc8c216be34a8280d1f8e2d9f82d3d93a755f772d2537e14b25 tokenNotFound: summary: Token does not exist or has expired value: response_code: 3 response_message: Token Not Found x-microcks-operation: delay: 0 dispatcher: FALLBACK x-microcks-default: tokenIssued components: schemas: ResponseEnvelope: type: object description: >- Standard response envelope used across all Open Trivia Database endpoints. The `response_code` field signals success or the specific failure mode that occurred. required: - response_code properties: response_code: type: integer description: >- Outcome code: 0 success, 1 no results (not enough questions), 2 invalid parameter, 3 token not found, 4 token empty (all questions served), 5 rate limit exceeded. enum: - 0 - 1 - 2 - 3 - 4 - 5 example: 0 response_message: type: string description: Human-readable description of the response code (returned for token endpoints). example: Token Generated Successfully! Question: type: object description: A single trivia question with its category, difficulty, and answers. required: - type - difficulty - category - question - correct_answer - incorrect_answers properties: type: type: string description: Question format — multiple-choice or true/false. enum: - multiple - boolean example: multiple difficulty: type: string description: Difficulty level assigned to the question. enum: - easy - medium - hard example: medium category: type: string description: Human-readable category name (HTML-entity encoded by default). example: Science & Nature question: type: string description: The trivia question prompt, encoded per the `encode` parameter. example: What is the chemical symbol for gold? correct_answer: type: string description: The correct answer to the question. example: Au incorrect_answers: type: array description: One incorrect answer for boolean questions, or three for multiple-choice. items: type: string example: - Ag - Go - Gd QuestionResponse: allOf: - $ref: '#/components/schemas/ResponseEnvelope' - type: object description: Response envelope returned by /api.php containing the question batch. required: - results properties: results: type: array description: Array of trivia questions matching the request parameters. items: $ref: '#/components/schemas/Question' Category: type: object description: A trivia category identifier and name pair. required: - id - name properties: id: type: integer description: Numeric category identifier. minimum: 9 maximum: 32 example: 9 name: type: string description: Human-readable category name. example: General Knowledge CategoryListResponse: type: object description: Response returned by /api_category.php. required: - trivia_categories properties: trivia_categories: type: array description: All trivia categories currently available in the database. items: $ref: '#/components/schemas/Category' CategoryQuestionCount: type: object description: Question counts for a single category broken down by difficulty. required: - total_question_count - total_easy_question_count - total_medium_question_count - total_hard_question_count properties: total_question_count: type: integer description: Total number of questions across all difficulty levels for this category. example: 469 total_easy_question_count: type: integer description: Number of easy questions in this category. example: 215 total_medium_question_count: type: integer description: Number of medium-difficulty questions in this category. example: 177 total_hard_question_count: type: integer description: Number of hard questions in this category. example: 77 CategoryCountResponse: type: object description: Response returned by /api_count.php. required: - category_id - category_question_count properties: category_id: type: integer description: Numeric identifier for the requested category. example: 9 category_question_count: $ref: '#/components/schemas/CategoryQuestionCount' GlobalCounts: type: object description: Aggregate question counts at either the global or per-category level. required: - total_num_of_questions - total_num_of_pending_questions - total_num_of_verified_questions - total_num_of_rejected_questions properties: total_num_of_questions: type: integer description: Total number of questions in this scope, regardless of moderation state. example: 21531 total_num_of_pending_questions: type: integer description: Questions submitted but not yet reviewed by moderators. example: 10828 total_num_of_verified_questions: type: integer description: Questions reviewed and approved by moderators (served by /api.php). example: 5296 total_num_of_rejected_questions: type: integer description: Questions reviewed and rejected by moderators. example: 5424 GlobalCountResponse: type: object description: Response returned by /api_count_global.php. required: - overall - categories properties: overall: $ref: '#/components/schemas/GlobalCounts' categories: type: object description: >- Per-category breakdown keyed by numeric category identifier as a string. Each value uses the same shape as the `overall` block. additionalProperties: $ref: '#/components/schemas/GlobalCounts' TokenResponse: allOf: - $ref: '#/components/schemas/ResponseEnvelope' - type: object description: Response returned by /api_token.php. properties: token: type: string description: >- The session token. Present on `command=request` and on a successful `command=reset` call. example: 5b76e266e1955dc8c216be34a8280d1f8e2d9f82d3d93a755f772d2537e14b25 securitySchemes: {} security: []