The API documentation for QB Reader.

Base URL: https://www.qbreader.org/api

The base URL for the multiplayer API is qbreader.org/api/multiplayer (Note: There is only one multiplayer API endpoint.)

You can find the python wrapper module for the API here: https://github.com/qbreader/python-module.

New rooms are created on the server when a WebSocket connection is established.

GET requests should always have parameters passed through the URI, and POST requests should have parameters passed through the body.

The API is rate-limited to 20 requests per second.

• GET qbreader.org/api/check-answer
  Parameters:
  • answerline - the answerline of the question. Preferably including the html tags <b> and <u>, if they are present.
  • givenAnswer - the answer the user gave.
  • returns: an array [directive, directedPrompt]
    • Example: [ "prompt", "of what status?" ]
    • Example: [ "accept", null ]
    • directive either equals accept, reject, or prompt
    • directedPrompt equals a string if there is a directed prompt, and null otherwise
• GET qbreader.org/api/num-packets
  Parameters:
  • setName - the name of the set (URI-encoded).
  • returns: a string that represents the number of packets in the set.
    • Example: 23
    • If the set name is not found, returns a 404 Not Found status and a response of 0
• GET qbreader.org/api/packet
  Parameters:
  • setName - the name of the set (URI-encoded).
  • packetNumber - the number of the packet in the set, starting from 1.
  • returns - a JSON object representing the packet you requested in the format { tossups: [{}, ...], bonuses: [{}, ...] }
• GET qbreader.org/api/packet-bonuses
  If you are only interested in the bonuses, this is twice as fast as using /api/packet
  Parameters:
  • setName - the name of the set (URI-encoded).
  • packetNumber - the number of the packet in the set, starting from 1.
  • returns - a JSON object representing the bonuses from the packet you requested in the format { tossups: [], bonuses: [{}, ...] }
    • If the set is not found, returns a 404 Not Found status and an (empty) packet that equals { tossups: [], bonuses: [] }
• GET qbreader.org/api/packet-tossups
  If you are only interested in the tossups, this is twice as fast as using /api/packet
  Parameters:
  • setName - the name of the set (URI-encoded).
  • packetNumber - the number of the packet in the set, starting from 1.
  • returns - a JSON object representing the bonuses from the packet you requested in the format { tossups: [{}, ...], bonuses: [] }
    • If the set is not found, returns a 404 Not Found status and an (empty) packet that equals { tossups: [], bonuses: [] }
• GET qbreader.org/api/query
  Parameters:
  • questionType - a string that either equals "tossup", "bonus", or "all". Otherwise, returns a 400 Bad Request response.
  • searchType - a string that either equals "question", "answer", or "all". Otherwise, returns a 400 Bad Request response.
  • [optional] queryString - a string that the query is searching for.
    • If undefined or omitted, it defaults to an empty string.
  • [optional] regex - a boolean that indicates whether queryString should be treated as a regular expression.
    • If undefined or omitted, it defaults to false.
  • [optional] randomize - a boolean that indicates whether the results should be in random order.
    • If undefined or omitted, it defaults to false.
  • [optional] setName - a string that is the name of the set to search in.
    • If undefined or omitted, then all sets are searched.
  • [optional] difficulties - an array of numbers representing the valid possible difficulties.
    • If undefined or omitted, then all difficulties are allowed.
    • Can also be a string or number if there is only 1 difficulty you want to select.
  • [optional] categories - an array of strings that contain the allowed categories.
    • If undefined or omitted, then all categories are allowed.
    • Can also be a string if there is only 1 category.
    • Take special care to ensure that the first letter of each word of the category is capitalized.
  • [optional] subcategories - an array of strings that contain the allowed subcategories.
    • If undefined or omitted, then all subcategories are allowed.
    • Can also be a string if there is only 1 subcategory.
    • Take special care to ensure that the first letter of each word of the subcategory is capitalized.
    • This api endpoint does not check for consistency between categories and subcategories.
    • For example, requesting the "history" and the "biology" and "chemistry" subcategories will return no questions.
  • [optional] maxReturnLength - a number that specifies the maximum number of questions to return
    • If 0, negative, undefined, or omitted, then the default is 50.
    • If greater than 200, the query will return no more than 200 questions.
  • returns - a JSON object of questions.
• GET qbreader.org/api/random-name
  Takes no parameters.
  • returns - a random adjective-noun pair that can be used as a name.
    • Example: amiable-emu
• POST qbreader.org/api/random-question
  Parameters:
  • questionType - a string that either equals "tossup" or "bonus". Otherwise, returns a 400 Bad Request response.
  • [optional] difficulties - an array of numbers representing the valid possible difficulties.
    • If undefined or omitted, then all difficulties are allowed.
    • Can also be a string or number if there is only 1 difficulty you want to select.
  • [optional] categories - an array of strings that contain the allowed categories.
    • If undefined or omitted, then all categories are allowed.
    • Can also be a string if there is only 1 category.
    • Take special care to ensure that the first letter of each word of the category is capitalized.
  • [optional] subcategories - an array of strings that contain the allowed subcategories.
    • If undefined or omitted, then all subcategories are allowed.
    • Can also be a string if there is only 1 subcategory.
    • Take special care to ensure that the first letter of each word of the subcategory is capitalized.
    • This api endpoint does not check for consistency between categories and subcategories.
    • For example, requesting the "history" and the "biology" and "chemistry" subcategories will return no questions.
  • [optional] number - a number that specifies how many questions to return (the length of the return array).
    If undefined or omitted, returns 1 question.
  • [optional] minYear - a number (default: 2010)
  • [optional] maxYear - a number (default: 2023)
  • returns - a JSON array of random questions.
    • If a question is not found, returns a 404 Not Found status.
• POST qbreader.org/api/report-question
  Parameters:
  • _id - the id of the question being reported.
  • [optional] reason - the reason why the question is being reported.
  • [optional] description - a description of the problem.
  • returns - a 200 status code if the operation was successful and a 500 status code if there was an error.
• GET qbreader.org/api/set-list
  Takes no parameters.
  • returns - An array of strings representing the names of the sets.
• GET qbreader.org/api/multiplayer/room-list
  Takes no parameters.
  • returns - A Javascript object whose keys are room names and whose values are arrays of the form [number of players, number of active players].
  • Only returns public rooms.