POST /api/v1/exams/papers

Create an exam

Creates an exam paper. Generation is asynchronous — returns 202 Accepted with a paper_id and status: pending. Await the exam.completed webhook or poll Retrieve an exam.

Parameters

Name	Type	Required	Description
`user_id`	string	required	Your identifier for the student (billing)
`exam.subject_id`	uuid	required	Subject (must be exam-enabled on your subscription)
`exam.topic_ids`	array	required	One or more topic UUIDs under the subject
`exam.duration_minutes`	integer	required	`30`, `45`, or `60`
`exam.target_difficulty`	string	optional	`easy`, `medium` (default), `hard`, or `mixed`
`exam.focus`	string	optional	Free-text focus area

Returns

A pending paper with paper_id, total_marks, and a poll_url.

cURL

curl -X POST "https://ai.intu.com.au/api/v1/exams/papers" \
  -H "Authorization: Token token=sk_intu_api_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "student-001",
    "exam": {
      "subject_id": "b1d9b7d4-06bc-45d1-95af-a441eb9b928b",
      "topic_ids": ["d85701b5-f957-4219-8bbf-eb3400f73990"],
      "duration_minutes": 60,
      "target_difficulty": "hard"
    }
  }'

Response

{
  "paper_id": "f0a1b2c3-...",
  "status": "pending",
  "subject": { "id": "b1d9b7d4-...", "name": "HSC Biology" },
  "duration_minutes": 60,
  "target_difficulty": "hard",
  "total_marks": 50,
  "poll_url": "https://ai.intu.com.au/api/v1/exams/papers/f0a1b2c3-..."
}