Open Trivia Database API

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: []