Open Trivia Database Questions API

openapi: 3.0.3
info:
  title: Open Trivia Database Categories Questions 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
security: []
tags:
- name: Questions
  description: Operations for retrieving trivia questions from the database.
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
components:
  schemas:
    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'
    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!