Quiz Question Generation API

Contents

• Authentication
• Pagination
• Endpoints
  • POST /questions
  • GET /quiz
  • POST /file/upload
  • GET /report/quiz/{id}
  • GET /languages

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 /report/quiz/{id}, 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. After calling this, you'll need to poll the quiz endpoint to get the completed quiz.

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.
upload_ids	array	No	[]	An array of upload IDs to generate questions from. This is used in conjunction with the file upload endpoint.
import_mode	boolean	No	false	If set to true, questions will be imported from the uploaded file(s) rather than generated. Use this in conjunction with upload_ids.
subtopics	array	No	[]	An array of subtopics to guide the question generation. Maximum 5 subtopics.

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:

    {
      "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_description": false,
  "redirect_to_quiz": false,
  "prevent_quiz_restart": false,
  "status": "completed",
  "total_quiz_views": 0,
  "total_embed_quiz_views": 0,
  "subject_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
        }
      ]
    }
  ]
}

POST /file/upload

Upload a file to generate questions from. Most documents and images with text are supported. This endpoint will store the file and then return an upload_id, plus subtopics that you can optionally pick from to guide the question generation.

Endpoint

POST https://quizgecko.com/api/v1/file/upload

Example request:

curl --request POST \
  --url https://quizgecko.com/api/v1/file/upload \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'Content-Type: multipart/form-data' \
  --form '[email protected]'

Example response:

{
    "question": "Which specific aspects of this actor's career are you interested in?",
    "subtopics": [
        "film debut",
        "television appearances",
        "awards and accolades",
        "notable performances",
        "versatility"
    ],
    "upload_id": 122135
}

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",
  ...
}