Quizgecko API

Automate your quiz question generation workflow. Perfect for LMS platforms or website integrations. Please contact us to get access.

Getting a key

To access our API, please complete this form

Contents

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, are paginated. Simply pass the page param along with the request to return the next page. E.g. ?page=2

Concepts

Understanding the following concepts is essential for working with our API:

  • Quiz - A quiz is the primary container for educational content. In our user interface, this is now referred to as a "Lesson". Each quiz object has a unique ID and contains various types of content.
  • Questions - These are assessment items contained within a quiz. Questions can be multiple choice, true/false, or other formats.
  • Flashcards - Learning aids contained within a quiz, typically consisting of a term and definition pair.
  • Study Notes - Text content associated with a quiz that provides additional context or learning material.

Note: While podcasts may be available in our user interface, they are not included in API responses.

Endpoints

POST /generate

Generate questions content. After calling this, you'll need to poll the quiz endpoint to get the completed quiz.

Endpoint

POST https://quizgecko.com/api/v1/generate

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.
custom_instructions string No null Custom instructions to guide the AI when generating questions. Maximum 1000 characters.

Example request:

curl -X "POST" "https://quizgecko.com/api/v1/generate" \
    -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 /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",
  ...
}
  
            

PUT /questions/{id}

Update an existing question and its associated answers. Can modify the question text, info, and answers in a single request.

Endpoint

PUT https://quizgecko.com/api/v1/generate/{id}

Parameters

Pass parameters in the request body as JSON.

Name Type Required Description
text string No The question text. Max 1800 chars.
answers array No Array of answer objects. Empty text will delete the answer.
info string No Additional context/info about the question. Max 1800 chars.

Example request:

curl -X PUT "https://quizgecko.com/api/v1/generate/14665662" \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
        "text": "Which element is referred to as the currency of life that provides energy to both animals and plants?",
        "info": "Carbon is often termed as the currency of life due to its fundamental role in biological systems.",
        "answers": [
            {
                "id": 49933758,
                "text": "Carbon",
                "correct": true
            },
            {
                "id": 49933759,
                "text": "Hydrogen",
                "correct": false
            },
            {
                "id": 49933760,
                "text": "Oxygen",
                "correct": false
            },
            {
                "id": 49933761,
                "text": "Nitrogen",
                "correct": false
            }
        ]
    }'

Example response:

{
    "id": 14665662,
    "text": "Which element is referred to as the currency of life that provides energy to both animals and plants?",
    "info": "Carbon is often termed as the currency of life due to its fundamental role in biological systems.",
    "answers": [
        {
            "id": 49933758,
            "text": "Carbon",
            "correct": true
        },
        {
            "id": 49933759,
            "text": "Hydrogen",
            "correct": false
        },
        {
            "id": 49933760,
            "text": "Oxygen",
            "correct": false
        },
        {
            "id": 49933761,
            "text": "Nitrogen",
            "correct": false
        }
    ]
}

PUT /quiz/{id}

Update a quiz's basic details like title and description.

Endpoint

PUT https://quizgecko.com/api/v1/quiz/{id}

Parameters

Pass parameters in the request body as JSON.

Name Type Required Description
title string No The quiz title.
description string No The quiz description.

Example request:

curl -X PUT "https://quizgecko.com/api/v1/quiz/911365" \
    -H "Authorization: Bearer YOUR_API_KEY_HERE" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
        "title": "Management Perspectives Quiz",
        "description": "Test your knowledge on management perspectives with this quiz focusing on corporate responsibility and economic well-being. Explore concepts like financial and triple bottom line management, and understand how these frameworks influence company practices."
    }'

Example response:

{
    "id": 911365,
    "title": "Management Perspectives Quiz",
    "description": "Test your knowledge on management perspectives with this quiz focusing on corporate responsibility and economic well-being. Explore concepts like financial and triple bottom line management, and understand how these frameworks influence company practices.",
    "updated_at": "2024-03-14T15:32:52.000000Z"
}