Playground ↗ Postman ↗ Dashboard ↗
POST /v2/courses/{course_id}/generate-exam

Generate an exam

Generates a graded-style exam from a course — mixed MCQ, short answer, and worked-problem questions, with answer keys. Cached per (course_id, model, exam_size).

Request

Headers

HeaderRequiredNotes
X-API-Keyyes
X-External-User-Idyes (or X-User-Id)Must own the course
Content-Typeyesapplication/json

Path parameters

course_id string (UUID) required
The course to generate an exam from.

Body

exam_size integer default 30
Number of questions. Range 10–50.

Returns

{
  "exam": {
    "title": "Photosynthesis: From Light to Life — Final Exam",
    "instructions": "Answer all questions. Show working where applicable.",
    "questions": [
      {
        "type": "mcq",
        "prompt": "Which pigment is primarily responsible for absorbing blue and red light?",
        "choices": ["Carotenoid", "Chlorophyll-a", "Chlorophyll-b", "Xanthophyll"],
        "answer": 1,
        "explanation": "Chlorophyll-a peaks at 430 nm (blue) and 662 nm (red)…"
      },
      {
        "type": "short_answer",
        "prompt": "In one sentence, explain why C4 plants outperform C3 plants in hot, dry climates.",
        "answer": "C4 plants concentrate CO₂ around RuBisCO via the C4 pathway, suppressing photorespiration in low-CO₂ / high-temperature conditions.",
        "rubric": ["Mentions C4 pathway", "Identifies photorespiration suppression"]
      }
    ],
    "total": 30
  },
  "from_cache": false
}

Generating a 50-question exam can take 60–90s depending on the model. The call is synchronous — keep your HTTP timeout generous (≥120s) or trigger it from a background worker.

Errors

  • 404 — Course not found.
  • 422 — exam_size out of 10–50 range.
  • 503 — Upstream LLM unavailable.