Quiz Question Generation API
Automate your quiz question generation workflow. Perfect for LMS platforms or website integrations. Available on Business Premium and Enterprise plans only.
Getting a key
To access our API, please first subscribe to a paid plan with API credits. You can then generate a key from this page.
Documentation
Authentication
You need to pass your API key/token with every request, otherwise you will get a 401 Unauthenticated error.
The preferred method is Bearer authentication. Send your secret token in the
Authorization
header with the Bearer
keyword. E.g.
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" https://quizgecko.com/api/v1/test
For convenience, you can also pass your API key in the api_key
query parameter. E.g.
curl https://quizgecko.com/api/v1/test?api_key=YOUR_API_KEY_HERE
You can use the /test
endpoint as above to quickly check authentication is working.
Pagination
Some endpoints, e.g. /quiz
and /quiz/{id}/report
, are paginated. Simply pass
the page
param along with the request to return the next page. E.g. ?page=2
Endpoints
POST /questions
Generate questions by providing text or a URL.
Endpoint
POST https://quizgecko.com/api/v1/questions
Parameters
Pass parameters in the request body as JSON.
Name | Type | Required | Default | Description |
---|---|---|---|---|
text | string | Yes | The text to generate questions from. Min 400 characters. Maximum 20-25k characters depending on plan. Required if URL is not provided. | |
url | string | Yes | The URL to generate questions from. Must be a public, crawlable URL. Text is automatically trimmed after 5000 characters. Required if text is not provided. | |
question_type | string | No | auto | The type of questions to generate. Can be multiple_choice ,
short_answer , true_false or auto . Default is
auto .
|
number_of_questions | integer | No | auto | The approximate number of questions to generate. |
difficulty | string | No | easy | The difficulty of questions to generate. Can be easy ,
medium or hard . Defaults to easy .
|
language | string | No | en | The language of the text. Defaults to en . See the languages endpoint for a list of supported languages. |
async | boolean | No | false | Whether to return immediately with a quiz ID, or wait for the questions to be generated. Defaults to false. See the async docs for more details. |
Example request:
curl -X "POST" "https://quizgecko.com/api/v1/questions" \
-H 'Authorization: Bearer YOUR_API_KEY_HERE' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"url": "https://en.wikipedia.org/wiki/Physics",
"question_type": "multiple_choice",
"difficulty": "easy"
}'
Example response:
{
"data": [
{
"answer": "B",
"answer_text": "Nonviolent resistance",
"question": "What was Gandhi's main method of resistance?",
"type": "multiple_choice",
"choices": {
"A": "Violence",
"B": "Nonviolent resistance",
"C": "Political manipulation",
"D": "Bribery"
},
"answer_info": "He employed nonviolent resistance to lead India's successful campaign for independence from British rule."
},
{
"answer": "C",
"answer_text": "London",
"question": "Where did Gandhi train in law?",
"type": "multiple_choice",
"choices": {
"A": "Mumbai",
"B": "Delhi",
"C": "London",
"D": "New York"
},
"answer_info": "He was born in 1869 in coastal Gujarat and trained in law in London."
},
{
"answer": "B",
"answer_text": "Women's rights and religious and ethnic amity",
"question": "What were some of the causes that Gandhi led campaigns for in India?",
"type": "multiple_choice",
"choices": {
"A": "Animal rights and environmental protection",
"B": "Women's rights and religious and ethnic amity",
"C": "Gun control and military expansion",
"D": "Tax cuts and economic deregulation"
},
"answer_info": "He returned to India in 1915 and led nationwide campaigns for various causes, including poverty, women's rights, and religious and ethnic amity."
}
]
}
Async Mode
We now reccomend using the parameter to generate questions. In the future, we may deprecate the synchronus API or limit the input parameters.
If you set async
to true
, the API will return immediately with a quiz ID. You
can then use the quiz ID to fetch the questions once they have been generated.
We recommend polling the quiz API below every 10 seconds until the questions are ready. You can tell
when the quiz is ready, because the status
will become complete
.
Example Async response:
When you call /api/v1/questions
with async=true
, you will get an immediate
response like
this:
{
"job_dispatched": true,
"quiz": {
"user_id": 1,
"language": "hi",
"slug": "uhhvwyt9jj",
"updated_at": "2023-06-23T13:03:27.000000Z",
"created_at": "2023-06-23T13:03:27.000000Z",
"id": 37203,
"status": "processing",
"url": "https://quizgecko.test/quiz/uhhvwyt9jj",
"image": null,
"questions": []
},
"chunks": 4
}
GET /quiz
Fetch a quiz by ID, or leave out the ID to fetch all quizzes, paginated. Poll this endpoint to get the completed quiz, when quiz.status = completed. Use the same authentification as described above.
Endpoint
GET https://quizgecko.com/api/v1/quiz/{id}
Example request:
curl -X "GET" "https://quizgecko.com/api/v1/quiz/{id}"
Example response:
{
"id": 37199,
"folder_id": null,
"user_id": 1,
"title": "The Life and Legacy of Mahatma Gandhi",
"slug": "the-life-and-legacy-of-mahatma-gandhi-0NQpds",
"description": "Test your knowledge on the life of Mahatma Gandhi...",
"published_at": null,
"generation_id": null,
"created_at": "2023-06-22T21:14:04.000000Z",
"updated_at": "2023-06-22T21:36:49.000000Z",
"deleted_at": null,
"friendly_slug_generated_at": "2023-06-22T21:14:13.000000Z",
"visibility": "Public",
"email_required": "not_required",
"hide_flashcards": false,
"hide_summary_notes": false,
"hide_question_preview": false,
"hide_description": false,
"redirect_to_quiz": false,
"prevent_quiz_restart": false,
"status": "completed",
"total_quiz_views": 0,
"total_embed_quiz_views": 0,
"quiz_category_id": null,
"language": "en",
"shuffle_questions": false,
"summary": null,
"image_path": null,
"math_mode": 0,
"url": "https://quizgecko.com/quiz/the-life-and-legacy-of-mahatma-gandhi-0NQpds",
"image": null,
"questions": [
{
"id": 191316,
"quiz_id": 37199,
"type": "fill_in_the_blank",
"text": "Mohandas Karamchand Gandhi was an Indian _______.",
"number": 0,
"points": 1,
"created_at": "2023-06-22T21:14:09.000000Z",
"updated_at": "2023-06-22T21:14:09.000000Z",
"info": null,
"deleted_at": null,
"answers": [
{
"id": 654070,
"question_id": 191316,
"text": "lawyer",
"order": 1,
"correct": 1,
"created_at": "2023-06-22T21:14:09.000000Z",
"updated_at": "2023-06-22T21:14:09.000000Z",
"deleted_at": null
}
]
}
]
}
GET /report/quiz/{id}
Fetch a report for a quiz ID. Includes stats, sessions (paginated) and participants. Use the same authentification as described above.
Endpoint
GET https://quizgecko.com/api/v1/report/quiz/{id}
Example request:
curl -X "GET" "https://quizgecko.com/api/v1/report/quiz/{id}"
Example response:
{
"data": {
"quiz": {
"quiz_id": 37204,
"title": "Discover the Life and Legacy of Mahatma Gandhi",
"description": "Test your knowledge on Mahatma Gandhi, the Indian lawyer and political leader who led the nonviolent movement for India's independence from British rule. Learn about his life, achievements, and contributions to civil rights and freedom in this quiz.",
"slug": "discover-the-life-and-legacy-of-mahatma-gandhi-iFX6tG",
"question_count": 2
},
"stats": {
"views": {
"embed": 0,
"regular": 0,
"total": 0
},
"sessions": {
"total": 3,
"completed": 3,
"completion_rate": 100,
"in_progress": 0,
"not_started": 0,
"unique": 1,
"unique_completed": 1,
"unique_completion_rate": 100
},
"average": {
"score": 35.333333333333336,
"time_taken": 30248.666666666668
},
"max_min": {
"highest_score": 40,
"lowest_score": 33,
"longest_time_taken": 90700,
"shortest_time_taken": 11
},
"score_distribution": {
"33": 2,
"40": 1
}
},
"sessions": [
{
"session_id": 1635,
"completion_status": "completed",
"participant_name": "John Doe",
"participant_email": "[email protected]",
"user_id": 1,
"score_percent": 33,
"completion_time_seconds": 35,
"started_at": "2023-06-28T12:33:16.000000Z",
"completed_at": "2023-06-28T12:33:51.000000Z",
"answers": [
{
"question": "Which country did Gandhi lead the successful campaign for independence from British rule?",
"question_id": 191336,
"answered_at": "2023-06-28T12:33:46.000000Z",
"participant_answer": "South Africa",
"correct": false,
"correct_answer": "India"
},
{
"question": "Where did Gandhi move to in 1893 to represent an Indian merchant in a lawsuit?",
"question_id": 191337,
"answered_at": "2023-06-28T12:33:49.000000Z",
"participant_answer": "England",
"correct": false,
"correct_answer": "South Africa"
}
]
}
]
}
}
GET /languages
Fetch a list of supported languages. You can also view the list as a text file here: https://quizgecko.com/api/v1/languages?text=1
Endpoint
GET https://quizgecko.com/api/v1/languages
Example request:
curl -X "GET" "https://quizgecko.com/api/v1/languages"
Example response:
{
"ab": "Abkhazian",
"ace": "Achinese",
"ach": "Acoli",
"ada": "Adangme",
"ady": "Adyghe",
"aa": "Afar",
"afh": "Afrihili",
...
}