openapi: 3.0.3
info:
  title: Open Trivia Database Categories 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: Categories
  description: Operations for discovering trivia category metadata and counts.
paths:
  /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
components:
  schemas:
    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
    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
    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'
    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'