Quizgecko API (V2)

Contents

• Authentication
• Response format
• Generation flow
• Endpoints
  • POST /api/v2/generate
  • GET /api/v2/courses/{course}/generation-status
  • GET /api/v2/courses/{course}
  • GET /api/v2/quizzes/{quiz}
  • PUT /api/v2/quizzes/{quiz}
  • Question create/update
  • GET /api/v2/usage
• Uploads as source content
• Errors

Authentication

All endpoints require your API key:

• Authorization: Bearer YOUR_API_KEY_HERE
• You can also pass ?api_key=YOUR_API_KEY_HERE for local testing.

Response format

V2 responses follow data / meta structure with snake_case keys. See docs/api/v2-api-response-structure.md for details.

{
  "data": {...},
  "meta": {...}
}

Generation flow

1. Send content to POST /api/v2/generate (text, URL, upload IDs, or topic).
2. Receive a course shell immediately (201) with generation_status = generating .
3. Poll GET /api/v2/courses/{course}/generation-status until status is completed or failed .
4. Fetch the finished course with GET /api/v2/courses/{course} (modules + activities).
5. Retrieve or edit the generated quiz via /api/v2/quizzes/{quiz} and related endpoints.

Endpoints

POST /api/v2/generate

Start course generation from text, URL, upload IDs, or topic. Returns a course shell immediately; background jobs handle outline, modules, quiz, flashcards, and study notes.

Endpoint

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

Body (JSON or multipart/form-data)

Name	Type	Required	Description
text	string	Required* if no other source	Source text (min ~400 chars). One of text, url, upload_ids, or topic is required.
url	string	Required* if no other source	Public, crawlable URL (YouTube validated for transcript availability).
upload_ids	array<int>	Required* if no other source	IDs from POST /api/v1/file/upload . Use when sending files.
topic	string	Required* if no other source	Topic-based generation without source text/URL.
quiz_id	int	No	Regenerate an existing quiz (Add More with AI). Forces question-only generation.
options.language	string	No	Two-letter code or auto (default: en ).
options.difficulty	string	No	auto | easy | medium | hard | very_hard | mixed (default: medium).
options.module_count	int	No	Number of modules to generate (default: 3, max: 10).
options.generate_questions	boolean	No	Generate quiz questions (default: true ).
options.generate_flashcards	boolean	No	Generate flashcards (default: true ).
options.generate_study_notes	boolean	No	Generate study notes (default: true ).
options.custom_instructions	string	No	Additional guidance for tone/style (max ~1000 chars).
options.question_type	string	No	Preferred question type (e.g. multiple_choice , short_answer ). Defaults to auto mix.
options.number_of_questions	int | "auto"	No	Per-quiz question target. Use auto to let the model decide.

Sample request

curl -X POST "https://quizgecko.com/api/v2/generate" \
 -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
   "text": "Photosynthesis is the process by which plants convert light energy...",
   "options": {
     "language": "en",
     "difficulty": "medium",
     "module_count": 3,
     "generate_questions": true,
     "generate_flashcards": true,
     "generate_study_notes": true,
     "question_type": "multiple_choice",
     "number_of_questions": "auto",
     "custom_instructions": "Keep explanations concise and student-friendly."
   }
 }'

Immediate response (201)

{
  "data": {
    "id": 1234,
    "title": null,
    "description": null,
    "slug": "course-1234",
    "generation_status": "generating",
    "generation_started_at": "2025-02-01T10:00:00Z",
    "generation_completed_at": null,
    "modules": [],
    "uploads": [],
    "links": [],
    "url": "/learn/course-1234"
  },
  "meta": {
    "message": "Course creation started",
    "resource_type": "course"
  }
}

When using quiz_id (regeneration), the response may be 202 with resource_type set to course or quiz depending on availability.

GET /api/v2/courses/{course}/generation-status

Poll generation status for a course. Use the course ID or slug from the generate response.

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 "https://quizgecko.com/api/v2/courses/1234/generation-status"

{
  "data": {
    "course_id": 1234,
    "slug": "course-1234",
    "generation_status": "generating",
    "generation_started_at": "2025-02-01T10:00:00Z",
    "generation_completed_at": null,
    "loading_messages": [
      "Creating outline...",
      "Generating module activities..."
    ],
    "currently_generating_module": {
      "id": 5678,
      "title": "Core Concepts",
      "order": 1
    },
    "practice_readiness": {
      "quiz_ready": false,
      "flashcards_ready": false,
      "study_notes_ready": false
    }
  },
  "meta": {
    "progress_percentage": 0,
    "total_modules": 3,
    "completed_modules": 0,
    "generating_modules": 1
  }
}

Status values: pending → generating → outline_created → generating → completed (or failed ).

GET /api/v2/courses/{course}

Fetch the generated course once status is completed. Includes modules and activities (quiz, flashcard_set, study_note).

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 "https://quizgecko.com/api/v2/courses/1234"

{
  "data": {
    "id": 1234,
    "title": "Photosynthesis Essentials",
    "description": "A short course on how plants convert light into energy.",
    "slug": "photosynthesis-essentials",
    "generation_status": "completed",
    "modules": [
      {
        "id": 5678,
        "title": "Core Concepts",
        "order": 1,
        "generation_status": "completed",
        "activities": [
          {
            "id": 9001,
            "type": "quiz",
            "order": 1,
            "data": {
              "id": 9001,
              "title": "Module 1 Quiz",
              "description": "Check your understanding.",
              "question_count": 8,
              "status": "published"
            },
            "readiness": {
              "is_ready": true
            }
          },
          {
            "id": 9002,
            "type": "flashcard_set",
            "order": 2,
            "data": {
              "id": 9002,
              "title": "Key Terms",
              "card_count": 12
            },
            "readiness": {
              "is_ready": true
            }
          },
          {
            "id": 9003,
            "type": "study_note",
            "order": 3,
            "data": {
              "id": 9003,
              "title": "Study Notes",
              "content_length": 820
            },
            "readiness": {
              "is_ready": true
            }
          }
        ]
      }
    ],
    "uploads": [],
    "links": [],
    "url": "/learn/photosynthesis-essentials"
  }
}

GET /api/v2/quizzes/{quiz}

Retrieve a generated quiz (e.g., from modules.activities.data.id where type = quiz ).

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 "https://quizgecko.com/api/v2/quizzes/9001"

{
  "data": {
    "id": 9001,
    "title": "Module 1 Quiz",
    "description": "Check your understanding.",
    "questions": [
      {
        "id": 1,
        "type": "multiple_choice",
        "question": "What is the primary pigment in photosynthesis?",
        "answers": [
          {"id": 11, "answer": "Chlorophyll", "is_correct": true},
          {"id": 12, "answer": "Hemoglobin", "is_correct": false}
        ]
      }
    ]
  }
}

PUT /api/v2/quizzes/{quiz}

Update quiz title/description or settings.

curl -X PUT "https://quizgecko.com/api/v2/quizzes/9001" \
 -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{"title":"Module 1 Quiz (Updated)","description":"Short check."}'

To reorder questions, call PUT /api/v2/quizzes/{quiz}/questions/reorder with {"questions":[{"id":1,"order":0},{"id":2,"order":1}]} .

Question create/update

• POST /api/v2/questions — create a new question for a quiz.
• PUT /api/v2/questions/{question} — update text/answers.
• POST /api/v2/questions/{question}/complete — mark editing complete (used by builder).

curl -X POST "https://quizgecko.com/api/v2/questions" \
 -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 -H "Content-Type: application/json" \
 -d '{
   "quiz_id": 9001,
   "type": "multiple_choice",
   "question": "Which gas is released during photosynthesis?",
   "answers": [
     {"answer": "Oxygen", "is_correct": true},
     {"answer": "Carbon dioxide", "is_correct": false}
   ]
 }'

GET /api/v2/usage

Check whether the authenticated user can generate more courses and view limits.

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 "https://quizgecko.com/api/v2/usage"

{
  "data": {
    "can_generate": true
  },
  "meta": {
    "monthly_limit": 50,
    "monthly_used": 12
  }
}

Uploads as source content

To use files as input, first upload via the existing v1 endpoint:

curl -X POST "https://quizgecko.com/api/v1/file/upload" \
 -H "Authorization: Bearer YOUR_API_KEY_HERE" \
 -F "file=@/path/to/document.pdf"

Then pass the returned upload_id in upload_ids when calling /api/v2/generate .

Errors

V2 uses standard Laravel validation and error responses. Examples:

{
  "message": "The given data was invalid.",
  "errors": {
    "text": [
      "Please provide either text, URL, file uploads, or topic."
    ]
  }
}

{
  "message": "You have reached your monthly course creation limit.",
  "meta": {
    "monthly_limit": 10,
    "monthly_used": 10
  }
}