openapi: 3.1.0
info:
  title: Open Trivia DB API
  description: >-
    Free JSON API providing trivia questions across multiple categories,
    difficulties, and types. No API key is required. Supports session tokens to
    avoid duplicate questions across requests, multiple response encodings, and
    rate limiting of one request per IP every 5 seconds.
  version: '1.0'
  contact:
    name: Open Trivia DB
    url: https://opentdb.com
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International
    url: https://creativecommons.org/licenses/by-sa/4.0/
externalDocs:
  description: Open Trivia DB API Documentation
  url: https://opentdb.com/api_config.php
servers:
  - url: https://opentdb.com
    description: Open Trivia DB Production
tags:
  - name: Questions
    description: Retrieve trivia questions.
  - name: Categories
    description: Retrieve available trivia categories.
  - name: Tokens
    description: Manage session tokens to track served questions.
paths:
  /api.php:
    get:
      tags:
        - Questions
      summary: Retrieve trivia questions
      description: >-
        Returns a list of trivia questions filtered by amount, category,
        difficulty, type, and encoding. Up to 50 questions per request.
      operationId: getQuestions
      parameters:
        - name: amount
          in: query
          required: true
          description: Number of questions to return (1-50).
          schema:
            type: integer
            minimum: 1
            maximum: 50
        - name: category
          in: query
          description: Category ID to filter by. Omit for any category.
          schema:
            type: integer
        - name: difficulty
          in: query
          description: Question difficulty.
          schema:
            type: string
            enum: [easy, medium, hard]
        - name: type
          in: query
          description: Question type.
          schema:
            type: string
            enum: [multiple, boolean]
        - name: encode
          in: query
          description: Response encoding format.
          schema:
            type: string
            enum: [url3986, base64]
        - name: token
          in: query
          description: Session token to avoid duplicate questions.
          schema:
            type: string
      responses:
        '200':
          description: Trivia questions response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionsResponse'
  /api_category.php:
    get:
      tags:
        - Categories
      summary: List trivia categories
      description: Returns all available trivia categories with IDs and names.
      operationId: getCategories
      responses:
        '200':
          description: List of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
  /api_count.php:
    get:
      tags:
        - Categories
      summary: Question count for category
      description: Returns the total and remaining question counts for a category.
      operationId: getCategoryCount
      parameters:
        - name: category
          in: query
          required: true
          description: Category ID.
          schema:
            type: integer
      responses:
        '200':
          description: Category question count.
  /api_count_global.php:
    get:
      tags:
        - Categories
      summary: Global question counts
      description: Returns global question counts across all categories.
      operationId: getGlobalCount
      responses:
        '200':
          description: Global counts response.
  /api_token.php:
    get:
      tags:
        - Tokens
      summary: Manage session tokens
      description: >-
        Request a new session token, reset an existing one, or check token
        status. Tokens prevent duplicate questions across requests for 6 hours
        of inactivity.
      operationId: manageToken
      parameters:
        - name: command
          in: query
          required: true
          description: Token operation.
          schema:
            type: string
            enum: [request, reset]
        - name: token
          in: query
          description: Existing token (required when command is reset).
          schema:
            type: string
      responses:
        '200':
          description: Token response.
components:
  schemas:
    QuestionsResponse:
      type: object
      properties:
        response_code:
          type: integer
          description: 0 = Success, 1 = No Results, 2 = Invalid Parameter, 3 = Token Not Found, 4 = Token Empty, 5 = Rate Limit.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Question'
    Question:
      type: object
      properties:
        category:
          type: string
        type:
          type: string
          enum: [multiple, boolean]
        difficulty:
          type: string
          enum: [easy, medium, hard]
        question:
          type: string
        correct_answer:
          type: string
        incorrect_answers:
          type: array
          items:
            type: string
    CategoriesResponse:
      type: object
      properties:
        trivia_categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string