{
  "openapi": "3.0.0",
  "info": {
    "title": "The Trivia API",
    "version": "1.0.0",
    "description": "# Introduction #\n\nThe Trivia API is a REST API used to request multiple choice trivia questions. No API key is required to request questions, but an API key can be used to gain access to further functionality, such as searching, quizzes, and sessions.\n\nAn API key is also required if you would like to use data from the API commercially.\n        "
  },
  "servers": [
    {
      "url": "https://the-trivia-api.com/v2"
    }
  ],
  "tags": [
    {
      "name": "The Question Model",
      "description": "<SchemaDefinition schemaRef=\"#/components/schemas/V2Question\" />"
    }
  ],
  "paths": {
    "/quizzes": {
      "get": {
        "operationId": "getMyQuizzes",
        "summary": "Get all quizzes for a given user",
        "description": "(Requires subscription)\n\nWill return all quizzes that were created using the API key send with this request.",
        "tags": ["Quizzes"],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Quiz"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/tags": {
      "get": {
        "operationId": "getTags",
        "summary": "Get all tags",
        "description": "Returns an array of all tags set on questions",
        "tags": ["Meta"],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "world_war_2",
                    "france",
                    "physics",
                    "architecture"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/tag-registry": {
      "get": {
        "operationId": "getTagRegistry",
        "summary": "List the tag vocabulary",
        "description": "Returns every active tag in the tag vocabulary, sorted by slug, with its label and description where it has them. These are the only tags a question can be given.\n\n`label` and `description` are objects keyed by language code, but they hold only the language requested with `language` (English, `en`, by default), never the others. If a tag has no text in the requested language, its English text is returned under the `en` key instead, so read `label[language] ?? label.en`. A tag with no label or description at all has no `label` or `description` field.\n\n`count` is the number of questions `GET /questions/count?tags=<slug>&types=<types>` reports for the tag: approved questions of the requested types that are suitable for every region, in every category and difficulty, including niche questions (because a tag is given), with no `language` or `contentFilter` narrowing. A tag with no questions has a `count` of 0. As with `GET /questions`, requesting `text_input` also counts `text_choice` questions that can be served as `text_input`, so counts for separate types can add up to more than the count for the types together.\n\nNo API key or subscription is needed for any type or language. When an API key is sent, the request counts against the key's monthly credits like every other API request.\n\nResponses may be cached for 5 minutes. A new or changed tag can take a further minute to appear, and counts can be up to a further 5 minutes behind newly approved questions.\n",
        "tags": ["Meta"],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "in": "query",
            "name": "types",
            "schema": {
              "type": "string",
              "default": "text_choice"
            },
            "description": "Comma separated list of the types of questions to count for each tag, as in `GET /questions/count`. If not provided, only `text_choice` questions are counted. No subscription is needed for any type.",
            "example": "text_choice,image_choice,text_input"
          },
          {
            "in": "query",
            "name": "language",
            "schema": {
              "type": "string",
              "enum": ["en", "es", "nl", "hi", "tr", "fr", "de", "ru", "pt"],
              "default": "en"
            },
            "description": "ISO 639-1 code of the language to return each tag's `label` and `description` in. Only that language is returned; a tag with no text in it has its English text under `en` instead. If not provided, English is returned. No API key or subscription is needed for any language, unlike the `language` parameter of `GET /questions`.",
            "example": "fr"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=300"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicTag"
                  }
                },
                "examples": {
                  "english": {
                    "summary": "Default: English",
                    "value": [
                      {
                        "slug": "place:france",
                        "label": { "en": "France" },
                        "description": {
                          "en": "France, its regions, cities, history and culture."
                        },
                        "count": 94
                      },
                      {
                        "slug": "place:turkey",
                        "label": { "en": "Turkey (country)" },
                        "description": {
                          "en": "Turkey, the country, its cities, history and culture."
                        },
                        "count": 21
                      }
                    ]
                  },
                  "french": {
                    "summary": "language=fr, with one tag falling back to English",
                    "value": [
                      {
                        "slug": "place:france",
                        "label": { "fr": "France" },
                        "description": {
                          "fr": "La France, ses régions, ses villes, son histoire et sa culture."
                        },
                        "count": 94
                      },
                      {
                        "slug": "place:turkey",
                        "label": { "en": "Turkey (country)" },
                        "description": {
                          "en": "Turkey, the country, its cities, history and culture."
                        },
                        "count": 21
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid `types` or `language`"
          },
          "503": {
            "description": "The tag vocabulary or the question counts could not be loaded"
          }
        }
      }
    },
    "/totals-per-tag": {
      "get": {
        "operationId": "getTotalsPerTag",
        "summary": "Get the total number of questions per tag",
        "description": "Takes the same input parameters as the `/questions` endpoint and returns a dictionary where each key is a tag and each value is the number of questions that have that tag for the given query parameters.",
        "tags": ["Meta"],
        "parameters": [
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "$ref": "#/components/parameters/typesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "integer"
                  },
                  "example": {
                    "world_war_2": 10,
                    "france": 5,
                    "physics": 3,
                    "architecture": 2
                  }
                }
              }
            }
          }
        }
      }
    },
    "/metadata": {
      "get": {
        "operationId": "getMetadata",
        "summary": "Get metadata on the questions that match a given query",
        "description": "Will return metadata on the questions that match the given query parameters.\nIncluding breakdowns by category, difficulty, status (approved/rejected/pending), and timestamps marking when the last questions matching the search were submitted and reviewed.",
        "tags": ["Meta"],
        "parameters": [
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "$ref": "#/components/parameters/typesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataResponse"
                }
              }
            }
          }
        }
      }
    },
    "/metadata/content-filter": {
      "get": {
        "operationId": "getContentFilterMetadata",
        "summary": "Get content filter metadata",
        "description": "Returns counts of approved questions by content-filter classification for the questions that match the given query parameters.\n\n- `family`: questions with `adultContent: false` (included when `contentFilter=family`)\n- `adult`: questions with `adultContent: true`\n- `unclassified`: questions with no `adultContent` field yet",
        "tags": ["Meta"],
        "parameters": [
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "$ref": "#/components/parameters/typesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentFilterMetadata"
                }
              }
            }
          }
        }
      }
    },
    "/languages": {
      "get": {
        "operationId": "getAllLanguages",
        "summary": "Get all languages that are supported by the API",
        "description": "Returns an array of all languages that are supported by the API",
        "tags": ["Meta"],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/question/{id}": {
      "get": {
        "operationId": "getQuestionById",
        "summary": "Get a question by id",
        "description": "Get a question by its id",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "tags": ["Questions"],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "description": "The id of the question to return",
            "example": "5f9f1b9b0e1b9c0017a5f1a5"
          },
          {
            "$ref": "#/components/parameters/languageQueryParam"
          },
          {
            "in": "query",
            "name": "showAnswer",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "For text_input questions, whether to include the correct answer and accepted answers in the response. Defaults to true.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "A question",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/TextChoiceQuestion"
                    },
                    {
                      "$ref": "#/components/schemas/ImageChoiceQuestion"
                    },
                    {
                      "$ref": "#/components/schemas/TextInputQuestion"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "An unsupported `language`, or a `showAnswer` that is not `true` or `false`"
          },
          "401": {
            "description": "No valid API key was sent, but the request needs one because it uses a `language` other than `en`. Send your key in the `X-API-Key` header."
          },
          "404": {
            "description": "No question found with the given id"
          }
        }
      }
    },
    "/question/{id}/report": {
      "post": {
        "operationId": "reportQuestion",
        "summary": "Report a question",
        "description": "Report a question as being incorrect or inappropriate",
        "tags": ["Questions"],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "description": "The id of the question to report",
            "example": "5f9f1b9b0e1b9c0017a5f1a5"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportQuestionBody"
              }
            }
          }
        }
      }
    },
    "/question/{id}/validate": {
      "post": {
        "operationId": "validateQuestionAnswer",
        "summary": "Validate an answer for a text_input question",
        "description": "(Require a complete subscription) Validates a user's free-form text answer against a text_input question. First checks against cached accepted answers, then uses LLM validation if no cached match is found.\n",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "tags": ["Questions"],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id of the text_input question",
            "example": "5f9f1b9b0e1b9c0017a5f1a5"
          },
          {
            "in": "query",
            "name": "language",
            "schema": {
              "type": "string",
              "default": "en"
            },
            "description": "The language code for the question/answer (ISO 639-1)",
            "example": "en"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["answer"],
                "properties": {
                  "answer": {
                    "type": "string",
                    "description": "The user's answer to validate",
                    "example": "Paris"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "isCorrect": {
                      "type": "boolean",
                      "description": "Whether the answer is correct"
                    },
                    "correctAnswer": {
                      "type": "string",
                      "description": "The correct answer"
                    },
                    "reason": {
                      "type": "string",
                      "description": "The reason for the validation result (from cache or LLM)"
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "cache",
                        "llm"
                      ],
                      "description": "Where the validation result came from: a cached answer, or the LLM"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (missing answer, invalid language, or question is not text_input type)"
          },
          "401": {
            "description": "No valid API key was sent. Send your key in the `X-API-Key` header."
          },
          "404": {
            "description": "No question found with the given id"
          }
        }
      }
    },
    "/questions": {
      "get": {
        "operationId": "getRandomQuestions",
        "summary": "Get a random set of questions",
        "description": "Get a random set of questions. Any combination of query parameters can be used, or you can omit all of them.\n\nPass an API Key in order to gain access to features that are behind a subscription, e.g.\n- More than 50 questions per request\n- High resolution images\n- Bypass the rate limiter",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "tags": ["Questions"],
        "parameters": [
          {
            "$ref": "#/components/parameters/limitQueryParam"
          },
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "$ref": "#/components/parameters/typesQueryParam"
          },
          {
            "$ref": "#/components/parameters/sessionQueryParam"
          },
          {
            "$ref": "#/components/parameters/previewQueryParam"
          },
          {
            "$ref": "#/components/parameters/languageQueryParam"
          },
          {
            "$ref": "#/components/parameters/queryQueryParam"
          },
          {
            "$ref": "#/components/parameters/contentFilterQueryParam"
          },
          {
            "$ref": "#/components/parameters/hasSourcesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of questions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/TextChoiceQuestion"
                      },
                      {
                        "$ref": "#/components/schemas/ImageChoiceQuestion"
                      },
                      {
                        "$ref": "#/components/schemas/TextInputQuestion"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter, e.g. a `limit` that is not a whole number of at least 1, an unrecognised category, difficulty or type, or an unsupported `language`"
          },
          "401": {
            "description": "No valid API key was sent, but the request needs one because it asks for `image_choice` or `text_input` types, a `language` other than `en`, or a semantic `query`. Send your key in the `X-API-Key` header."
          }
        }
      }
    },
    "/questions/count": {
      "get": {
        "operationId": "getQuestionCount",
        "summary": "Count the questions available for a set of filters",
        "description": "Returns the number of approved questions that `GET /questions` draws from when given the same query parameters. The same defaults apply: if `types` is not provided only `text_choice` questions are counted, if `tags` is not provided niche questions are excluded, and if `region` is not provided only questions suitable for every region are counted. `appliedFilters` shows the filters that were actually used.\n\nNo API key or subscription is needed for any parameter: every question type and language can be counted. When an API key is sent, the request counts against the key's monthly credits like every other API request.\n\n`limit` is accepted and ignored.\n\n`session`, `preview=true` and a non-empty `query` are not supported and return a 400. Counting a semantic `query` would need an embedding call, and its matches come from a capped candidate pool (up to 1000), so there is no exact total. To search questions, use `POST /questions/search`.\n\nResponses can be cached by browsers and CDNs for 60 seconds.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {}
        ],
        "tags": [
          "Questions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "in": "query",
            "name": "types",
            "schema": {
              "type": "string",
              "default": "text_choice"
            },
            "description": "Comma separated list of the types of questions to count. If not provided, only `text_choice` questions are counted, for parity with `GET /questions`; pass `types` explicitly to count other types (e.g. `text_choice,image_choice,text_input` for every type). No subscription is needed for any type.",
            "example": "image_choice,text_input"
          },
          {
            "$ref": "#/components/parameters/languageQueryParam"
          },
          {
            "$ref": "#/components/parameters/contentFilterQueryParam"
          },
          {
            "$ref": "#/components/parameters/hasSourcesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "The number of questions available for the given filters",
            "headers": {
              "Cache-Control": {
                "description": "Publicly cacheable for 60 seconds",
                "schema": {
                  "type": "string",
                  "example": "public, max-age=60, s-maxage=60"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionCountResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter (e.g. an unsupported `language`), or one of the unsupported `session`, `preview=true` or `query` parameters was used"
          },
          "429": {
            "description": "An API key was sent and this request would take it over its monthly credit limit"
          }
        }
      }
    },
    "/questions/search": {
      "post": {
        "operationId": "searchQuestions",
        "summary": "Search for questions",
        "description": "(Requires subscription)",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "tags": ["Questions"],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchQuestionsBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results, including a set of questions and information used to get more results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchQuestionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, e.g. a `perPage` or `pageNumber` that is not a whole number of at least 1"
          }
        }
      }
    },
    "/quiz/{id}": {
      "get": {
        "operationId": "getQuiz",
        "summary": "Get a quiz by ID.",
        "description": "Get a quiz by ID.",
        "tags": ["Quizzes"],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "description": "The ID of the quiz to get.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "language",
            "description": "The language to return questions in: `en`, `es`, `nl`, `hi`, `tr`, `fr`, `de`, `ru` or `pt`. Any other value returns a 400. Defaults to English.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The quiz.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quiz"
                }
              }
            }
          },
          "400": {
            "description": "An unsupported `language`"
          }
        }
      },
      "delete": {
        "operationId": "deleteQuiz",
        "summary": "Delete a quiz.",
        "description": "(Requires subscription)",
        "tags": ["Quizzes"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the quiz to delete.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The quiz was deleted."
          }
        }
      }
    },
    "/quiz": {
      "post": {
        "operationId": "createQuiz",
        "summary": "Create a quiz.",
        "description": "(Requires subscription)",
        "tags": ["Quizzes"],
        "requestBody": {
          "description": "The quiz to create.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "required": true,
                    "description": "User-friendly title for the quiz.",
                    "example": "Will's Dinosaur Quiz"
                  },
                  "questionIds": {
                    "type": "array",
                    "required": true,
                    "items": {
                      "type": "string",
                      "description": "The IDs of the questions to include on this quiz."
                    }
                  }
                },
                "required": ["title", "questionIds"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Information on the created quiz.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Unique ID for this quiz."
                    }
                  },
                  "required": ["id"]
                }
              }
            }
          }
        }
      }
    },
    "/session": {
      "post": {
        "operationId": "createSession",
        "summary": "Create a new session",
        "description": "(Requires Regular subscription)",
        "tags": ["Sessions"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The session id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/session/{id}": {
      "get": {
        "operationId": "getSession",
        "summary": "Get a session by id",
        "description": "(Requires Regular subscription)",
        "tags": ["Sessions"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string",
              "description": "The id of the session to return",
              "example": "1234567890"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "No session found with the given id"
          }
        }
      }
    },
    "/session/{id}/preview-questions": {
      "get": {
        "operationId": "previewSessionQuestions",
        "summary": "Get a session by id",
        "description": "Preview a session's questions. This is used to get a set of new questions for a session without marking them as 'used'. Questions generated in this way could be generated again on the same session unless they are manually marked as 'used'.",
        "tags": ["Sessions"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id of the session to preview questions for",
            "example": "1234567890"
          },
          {
            "$ref": "#/components/parameters/limitQueryParam"
          },
          {
            "$ref": "#/components/parameters/categoriesQueryParam"
          },
          {
            "$ref": "#/components/parameters/difficultiesQueryParam"
          },
          {
            "$ref": "#/components/parameters/regionQueryParam"
          },
          {
            "$ref": "#/components/parameters/tagsQueryParam"
          },
          {
            "$ref": "#/components/parameters/typesQueryParam"
          },
          {
            "$ref": "#/components/parameters/sessionQueryParam"
          },
          {
            "$ref": "#/components/parameters/hasSourcesQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of questions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/TextChoiceQuestion"
                      },
                      {
                        "$ref": "#/components/schemas/ImageChoiceQuestion"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/session/{id}/questions": {
      "post": {
        "operationId": "markQuestionsAsUsed",
        "summary": "Add used questions to a session",
        "description": "Is used to manually add questions to a session's array of 'used' questions, so that they won't be asked for this session.\n\nOrdinarily, questions are automatically added to this array, but sometimes (e.g.) when previewing questions, you may want to manually add questions.",
        "tags": ["Sessions"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "description": "The id of the session to add questions to",
            "example": "1234567890"
          }
        ],
        "requestBody": {
          "description": "A list of questions to add to the session",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "questionIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The ids of the questions to add to the session",
                    "example": ["1234567890", "0987654321"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Questions added to session"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "SearchQuestionsBody": {
        "type": "object",
        "properties": {
          "categories": {
            "description": "The categories to search for",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "order": {
            "description": "The order to sort the questions by, new questions are those that have been submitted most recently.",
            "type": "string",
            "enum": ["new", "old"]
          },
          "pageNumber": {
            "description": "The page number to return. Must be a whole number of at least 1. Defaults to 1.",
            "type": "integer",
            "minimum": 1
          },
          "perPage": {
            "description": "The number of questions to return per page. Must be a whole number of at least 1. A value above the number of questions per request that your subscription allows is capped to it, and the response's `perPage` shows the value used. Defaults to 10.",
            "type": "integer",
            "minimum": 1
          },
          "freetext": {
            "description": "Freetext value to search for withing question text",
            "type": "string"
          },
          "ids": {
            "description": "The ids of the questions to search for",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "description": "The tags to search for",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "difficulties": {
            "description": "The difficulty to search for",
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["easy", "medium", "hard"]
            }
          },
          "types": {
            "description": "The types to search for",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "description": "The region to search for",
            "type": "string"
          },
          "contentFilter": {
            "description": "Content filter to apply. When set to \"family\", excludes questions marked as adult content.",
            "type": "string",
            "enum": ["all", "family"]
          },
          "mode": {
            "description": "Search mode. 'text' will use keyword search, and will match questions that contain the exact search query in the question text. 'semantic' is only available with a Complete subscription, and will use semantic search to match questions that are semantically similar to the search query, e.g. \"Ancient civilizations\" will match questions containing the text \"Pyramids\", \"The Romans\", \"The bronze age\", etc. Defaults to text.",
            "type": "string",
            "enum": ["text", "semantic"]
          },
          "query": {
            "description": "Query used by the selected search mode.",
            "type": "string"
          },
          "language": {
            "description": "(Requires a Complete subscription) ISO 639-1 code of the language to return questions in. If not provided, questions will be returned in English.",
            "type": "string",
            "example": "es"
          },
          "hasSources": {
            "description": "When `true`, only questions with at least one source URL are returned. `false`, or not providing it, applies no filter. A value that is not a boolean returns a 400.",
            "type": "boolean",
            "example": true
          }
        }
      },
      "SearchQuestionsResponse": {
        "type": "object",
        "properties": {
          "questions": {
            "type": "array",
            "description": "The questions that match the search criteria",
            "items": {
              "$ref": "#/components/schemas/V2Question"
            }
          },
          "totalHits": {
            "type": "number",
            "description": "The total number of questions that match the search criteria"
          },
          "perPage": {
            "type": "number",
            "description": "The number of questions returned per page"
          },
          "pageNumber": {
            "type": "number",
            "description": "The page number returned"
          },
          "totalPages": {
            "type": "number",
            "description": "The total number of pages when the current search criteria is applied. Sending a request with a page number greater than this will return an empty array of questions."
          }
        },
        "required": [
          "questions",
          "totalHits",
          "perPage",
          "pageNumber",
          "totalPages"
        ]
      },
      "QuestionCountResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "The number of approved questions that `GET /questions` draws from for the applied filters",
            "example": 1234
          },
          "appliedFilters": {
            "type": "object",
            "description": "The filters used to calculate `count`. `categories`, `difficulties` and `types` are always present and include any defaults that were applied (`types` defaults to `text_choice`). The other filters are only present if they were provided in the request, and `hasSources` only when it is `true`, as `false` applies no filter.",
            "properties": {
              "categories": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Category"
                }
              },
              "difficulties": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "easy",
                    "medium",
                    "hard"
                  ]
                }
              },
              "types": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "text_choice",
                    "image_choice",
                    "text_input"
                  ]
                },
                "example": [
                  "text_choice"
                ]
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "rome"
                ]
              },
              "region": {
                "type": "string",
                "example": "GB"
              },
              "language": {
                "type": "string",
                "example": "en"
              },
              "contentFilter": {
                "type": "string",
                "enum": [
                  "all",
                  "family"
                ]
              },
              "hasSources": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "categories",
              "difficulties",
              "types"
            ]
          }
        },
        "required": [
          "count",
          "appliedFilters"
        ]
      },
      "BaseQuestion": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "$ref": "#/components/schemas/Category"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for the question",
            "example": "5f9f1b9b0e1b9c0017a5f1a5"
          },
          "tags": {
            "type": "array",
            "description": "Secondary categories for the question, as slugs from the closed tag vocabulary, such as \"place:france\". A question can have multiple tags. Creating or updating a question with a tag outside the vocabulary, or a deactivated one, is rejected; questions that have not been re-tagged yet may still carry older free-form tags.",
            "items": {
              "type": "string"
            },
            "example": ["category:geography", "place:france", "place:capital-cities"]
          },
          "difficulty": {
            "type": "string",
            "enum": ["easy", "medium", "hard"],
            "description": "How difficult the question is perceived to be by the moderators of the API."
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "If the question is regional (i.e. only reasonable to ask people from a particular set of countries), then the ISO 3166-1 alpha-2 country codes for those countries are specified here.\n\nFor most questions, this will be an empty array, meaning that the question is suitable to ask to people from anywhere in the world."
          },
          "isNiche": {
            "type": "boolean",
            "description": "Will be true if the question is a niche question, i.e. if it is considered too difficult to return unless the tag is specifically requested."
          }
        },
        "required": ["category", "id", "tags", "isNiche", "difficulty"]
      },
      "Category": {
        "type": "string",
        "enum": [
          "music",
          "sport_and_leisure",
          "film_and_tv",
          "arts_and_literature",
          "history",
          "society_and_culture",
          "science",
          "geography",
          "food_and_drink",
          "general_knowledge"
        ]
      },
      "ImageChoiceQuestion": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseQuestion"
          },
          {
            "type": "object",
            "properties": {
              "question": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "String formulation of the questions",
                    "example": "Which of these photos shows The Eiffel Tower?"
                  }
                },
                "required": ["text"]
              },
              "correctAnswer": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ImageOption"
                }
              },
              "incorrectAnswers": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ImageOption"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": ["image_choice"],
                "example": "image_choice"
              }
            },
            "required": [
              "question",
              "correctAnswer",
              "incorrectAnswers",
              "type"
            ]
          }
        ]
      },
      "ImageOption": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Full URL of the image",
            "example": "https://example.com/images/12345/an-interesting-image.jpg"
          },
          "height": {
            "type": "number",
            "description": "Height of the image in pixels",
            "example": 400
          },
          "width": {
            "type": "number",
            "description": "Width of the image in pixels",
            "example": 300
          },
          "size": {
            "type": "number",
            "description": "Size of the image in bytes",
            "example": 256612
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The author's name",
                "example": "John Smith"
              },
              "url": {
                "type": ["string", "null"],
                "description": "URL to the author's website or social media profile",
                "example": "https://john-smith.example.com"
              }
            }
          },
          "source": {
            "type": "object",
            "properties": {
              "url": {
                "type": ["string", "null"],
                "description": "Where the image is originally credited",
                "example": "https://example.com/some-source-gallery"
              }
            }
          },
          "description": {
            "type": "string",
            "description": "Description of what the image is showing, can be used as alt text.",
            "example": "A picture of a cat"
          },
          "license": {
            "type": "object",
            "properties": {
              "url": {
                "type": ["string", "null"],
                "description": "URL to the license of the image",
                "example": "https://creativecommons.org/licenses/by/4.0/"
              },
              "name": {
                "type": "string",
                "description": "Name of the license",
                "example": "Creative Commons Attribution 4.0 International"
              }
            }
          }
        },
        "required": [
          "url",
          "height",
          "width",
          "size",
          "author",
          "source",
          "description",
          "license"
        ]
      },
      "V2Question": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextChoiceQuestion"
          },
          {
            "$ref": "#/components/schemas/ImageChoiceQuestion"
          },
          {
            "$ref": "#/components/schemas/TextInputQuestion"
          }
        ]
      },
      "TextChoiceQuestion": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseQuestion"
          },
          {
            "type": "object",
            "properties": {
              "question": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "String formulation of the questions",
                    "example": "What is the capital of France?"
                  }
                },
                "required": ["text"]
              },
              "correctAnswer": {
                "type": "string",
                "description": "The correct answer",
                "example": "Paris"
              },
              "incorrectAnswers": {
                "type": "array",
                "description": "Array of incorrect answers",
                "example": ["London", "Berlin", "Brussels"],
                "items": {
                  "type": "string",
                  "description": "An incorrect answer"
                }
              },
              "hint": {
                "type": "string",
                "description": "A one-sentence clue to show before the player answers, if they ask for one. It points towards the answer without giving it away. Optional: not every question has one yet, and it is currently only returned for English requests.",
                "example": "Think of a city famous for a tower built for the 1889 World's Fair."
              },
              "explanation": {
                "type": "string",
                "description": "One or two sentences to show after the player answers, saying why the correct answer is right or adding a related fact. It names the correct answer, so do not show it before the player has answered. Optional: not every question has one yet, and it is currently only returned for English requests.",
                "example": "Paris is France's capital and largest city; London, Berlin and Brussels are the capitals of the UK, Germany and Belgium."
              },
              "sources": {
                "$ref": "#/components/schemas/QuestionSources"
              },
              "type": {
                "type": "string",
                "enum": ["text_choice"],
                "example": "text_choice"
              }
            },
            "required": [
              "question",
              "correctAnswer",
              "incorrectAnswers",
              "type"
            ]
          }
        ]
      },
      "TextInputQuestion": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseQuestion"
          },
          {
            "type": "object",
            "properties": {
              "question": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "String formulation of the question",
                    "example": "What is the chemical symbol for gold?"
                  }
                },
                "required": ["text"]
              },
              "correctAnswer": {
                "type": "string",
                "description": "The \"gold standard\" correct answer",
                "example": "Au"
              },
              "acceptedAnswers": {
                "type": "array",
                "description": "Cached list of accepted answer variations (only returned if showAnswer=true)",
                "example": ["Au", "AU", "au"],
                "items": {
                  "type": "string"
                }
              },
              "correctAnswerRatio": {
                "type": "object",
                "description": "How often this question has been answered correctly vs incorrectly",
                "properties": {
                  "correct": {
                    "type": "number",
                    "description": "Number of correct answers recorded"
                  },
                  "incorrect": {
                    "type": "number",
                    "description": "Number of incorrect answers recorded"
                  }
                },
                "required": ["correct", "incorrect"]
              },
              "hint": {
                "type": "string",
                "description": "A one-sentence clue to show before the player answers, if they ask for one. It points towards the answer without giving it away. Optional: not every question has one yet, and it is currently only returned for English requests.",
                "example": "The symbol comes from the metal's Latin name, not its English one."
              },
              "explanation": {
                "type": "string",
                "description": "One or two sentences to show after the player answers, saying why the correct answer is right or adding a related fact. It names the correct answer, so it is not returned when showAnswer=false. Optional: not every question has one yet, and it is currently only returned for English requests.",
                "example": "Gold's symbol Au comes from its Latin name, aurum, meaning 'shining dawn'."
              },
              "sources": {
                "$ref": "#/components/schemas/QuestionSources"
              },
              "type": {
                "type": "string",
                "enum": ["text_input"],
                "example": "text_input"
              }
            },
            "required": ["question", "correctAnswer", "correctAnswerRatio", "type"]
          }
        ]
      },
      "QuestionSources": {
        "type": "object",
        "description": "Links that support the question's correct answer. The key is omitted when the question has not been checked for sources yet. Sources are the same in every language.",
        "properties": {
          "urls": {
            "type": "array",
            "description": "0 to 3 https links supporting the answer. An empty array means the question was checked and no acceptable source was found.",
            "items": {
              "type": "string"
            }
          },
          "checkedAt": {
            "type": "string",
            "description": "When the sources were last checked, as an ISO 8601 date and time",
            "example": "2026-11-02T09:14:31.000+00:00"
          }
        },
        "required": ["urls", "checkedAt"],
        "example": {
          "urls": [
            "https://en.wikipedia.org/w/index.php?title=Paris&oldid=1254381947#:~:text=Paris%20is%20the%20capital%20and%20largest%20city%20of%20France",
            "https://www.britannica.com/place/Paris"
          ],
          "checkedAt": "2026-11-02T09:14:31.000+00:00"
        }
      },
      "Quiz": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique ID for this quiz."
          },
          "title": {
            "type": "string",
            "description": "User-friendly title for the quiz.",
            "example": "Will's Dinosaur Quiz"
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V2Question",
              "description": "The questions on this quiz."
            }
          }
        },
        "required": ["id", "title", "questions"]
      },
      "Session": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the session"
          },
          "totalQuestions": {
            "type": "number",
            "description": "Total questions available to the session"
          },
          "remainingQuestions": {
            "type": "number",
            "description": "Remaining questions left in the session"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp that the session was created"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp that the session was last updated"
          }
        },
        "required": [
          "id",
          "totalQuestions",
          "remainingQuestions",
          "createdAt",
          "updatedAt"
        ]
      },
      "LocalizedText": {
        "description": "Text keyed by ISO 639-1 language code. `GET /tag-registry` returns only the requested language, or `en` when a tag has no text in it.",
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "example": {
          "de": "Frankreich"
        }
      },
      "PublicTag": {
        "type": "object",
        "required": ["slug", "count"],
        "properties": {
          "slug": {
            "type": "string",
            "example": "place:france"
          },
          "label": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of questions of the requested `types` that `GET /questions/count?tags=<slug>&types=<types>` reports for this tag",
            "example": 94
          }
        }
      },
      "ReportQuestionBody": {
        "type": "object",
        "properties": {
          "reason": {
            "description": "The reason that this question is bad",
            "type": "string",
            "example": "The correct answer is listed as 'France' but it should be 'Spain'"
          }
        }
      },
      "MetadataResponse": {
        "type": "object",
        "description": "Metadata on the questions that match a given query",
        "properties": {
          "byCategory": {
            "description": "Number of matching questions per category",
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "example": {
              "history": 10,
              "geography": 5,
              "science": 3,
              "food_and_drink": 2
            }
          },
          "byDifficulty": {
            "description": "Number of matching questions per difficulty",
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "example": {
              "easy": 10,
              "medium": 5,
              "hard": 3
            }
          },
          "byState": {
            "description": "Number of matching questions per state",
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "example": {
              "approved": 10,
              "rejected": 5,
              "pending": 3
            }
          },
          "byType": {
            "description": "Number of matching questions per question type",
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "example": {
              "text_choice": 10,
              "image_choice": 5
            }
          },
          "lastCreated": {
            "description": "Timestamp of the most recently submitted matching question",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "lastReviewed": {
            "description": "Timestamp of the most recently reviewed matching question, null if none have been reviewed",
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2020-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "byCategory",
          "byDifficulty",
          "byState",
          "byType",
          "lastCreated",
          "lastReviewed"
        ]
      },
      "ContentFilterMetadata": {
        "type": "object",
        "description": "Counts of approved questions by content-filter classification",
        "properties": {
          "family": {
            "description": "Questions with `adultContent: false`",
            "type": "integer",
            "example": 12000
          },
          "adult": {
            "description": "Questions with `adultContent: true`",
            "type": "integer",
            "example": 800
          },
          "unclassified": {
            "description": "Questions with no `adultContent` field yet",
            "type": "integer",
            "example": 150
          }
        },
        "required": ["family", "adult", "unclassified"]
      }
    },
    "parameters": {
      "limitQueryParam": {
        "in": "query",
        "name": "limit",
        "description": "The number of questions to return. Must be a whole number of at least 1, otherwise the request returns a 400. A value above the maximum is capped to it: the maximum is 50 without an API key, or the number of questions per request that your subscription allows.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 10
        },
        "example": 5
      },
      "categoriesQueryParam": {
        "in": "query",
        "name": "categories",
        "description": "Comma separated list of categories to return questions from. If not provided, all categories will be used. An unrecognised category returns a 400.",
        "schema": {
          "type": "string"
        },
        "example": "science,film_and_tv"
      },
      "difficultiesQueryParam": {
        "in": "query",
        "name": "difficulties",
        "description": "Comma separated list of difficulties of questions to return. If not provided, all difficulties will be used.",
        "schema": {
          "type": "string",
          "default": "easy,medium,hard"
        },
        "example": "medium,hard"
      },
      "regionQueryParam": {
        "in": "query",
        "name": "region",
        "schema": {
          "type": "string"
        },
        "description": "Some questions are regional, i.e. only reasonable to ask people from a particular set of countries.\n\nIf not provided, all questions will be suitable to ask to people from anywhere in the world. If provided, you could also receive questions that are only suitable to ask to ask to people from the specified region, but not to people from all regions.\n\nThe region should be provided as an ISO 3166-1 alpha-2 country code.",
        "example": "GB"
      },
      "typesQueryParam": {
        "in": "query",
        "name": "types",
        "schema": {
          "type": "string",
          "default": "text_choice"
        },
        "description": "Comma separated list of the types of questions to return. If not provided, only text choice questions will be used.\nA Complete subscription is required to receive image questions.",
        "example": "text_choice,image_choice"
      },
      "tagsQueryParam": {
        "in": "query",
        "name": "tags",
        "schema": {
          "type": "string"
        },
        "description": "Comma separated list of tags to return questions from. If not provided, all tags will be used.",
        "example": "science,film_and_tv"
      },
      "sessionQueryParam": {
        "in": "query",
        "name": "session",
        "schema": {
          "type": "string"
        },
        "description": "The session id to return questions from. If not provided, questions will not come from a session, so could be duplicates of questions received on previous requests.",
        "example": "1234567890"
      },
      "previewQueryParam": {
        "in": "query",
        "name": "preview",
        "schema": {
          "type": "string",
          "enum": ["true", "false"]
        },
        "description": "When used with a session, this will not mark the generated questions as \"used\", so the same questions could be returned again in a future request. Questions generated in this way need to be manually marked as \"used\".",
        "example": true
      },
      "languageQueryParam": {
        "in": "query",
        "name": "language",
        "schema": {
          "type": "string"
        },
        "description": "(Requires a Complete subscription, except for `en`) ISO 639-1 code of the language to return questions in: `en`, `es`, `nl`, `hi`, `tr`, `fr`, `de`, `ru` or `pt`. Any other value returns a 400. If not provided, or `en`, questions are returned in English.",
        "example": "es"
      },
      "queryQueryParam": {
        "in": "query",
        "name": "query",
        "schema": {
          "type": "string"
        },
        "description": "Available with a Complete subscription, this will return questions that are semantically similar to the query. e.g. \"Ancient civilizations\" will match questions containing the text \"Pyramids\", \"The Romans\", \"The bronze age\", etc.",
        "example": "ancient%20civilizations"
      },
      "contentFilterQueryParam": {
        "in": "query",
        "name": "contentFilter",
        "schema": {
          "type": "string",
          "enum": ["all", "family"],
          "default": "all"
        },
        "description": "Content filter to apply. When set to \\\"family\\\", excludes questions marked as adult content."
      },
      "hasSourcesQueryParam": {
        "in": "query",
        "name": "hasSources",
        "schema": {
          "type": "boolean"
        },
        "description": "When `true`, only questions with at least one source URL (see `sources`) are included. `false`, or not providing it, applies no filter. Any other value returns a 400.",
        "example": true
      }
    }
  }
}
