Skip to content
Docs

Exams

Exams Overview

Create, publish and assign exams; read attempts, scores and analytics.

An exam belongs to a faculty owner and an app: grout (document and office exams in GroutApp) or groutcode (coding exams). Students see an exam once it is published and assigned to a group they belong to.

Create#

bash
curl -X POST $API/exams -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "faculty_id": "[email protected]",
  "title": "Data Structures Midterm",
  "exam_type": "exam",
  "max_score": 100,
  "due_date": "2026-10-01T09:00:00Z",
  "time_limit_minutes": 90,
  "allow_late_submission": false,
  "proctoring": { "camera": true, "screen": true },
  "ai_policy": { "allowed": true, "model_tier": "local", "max_interactions": 20 },
  "publish": true,
  "group_ids": ["grp_…"]
}'
FieldNotes
faculty_idRequired. Id or login email of the owning teacher.
exam_typeexam, homework, assignment, quiz, project
time_limit_minutesStarts a countdown when the student opens the exam.
proctoringWhat the student must enable before the exam opens. See Proctoring & AI Policy.
ai_policyRules for the in-app assistant.
code_specPresent ⇒ GroutCode coding exam. See GroutCode Coding Exams.
publishDefault true. Pass false to keep a draft.
group_idsAssign in the same call; students and verified guardians are emailed.

Lifecycle#

bash
curl -X POST $API/exams/ex_…/publish -H "Authorization: Bearer $KEY"
curl -X POST $API/exams/ex_…/close   -H "Authorization: Bearer $KEY"
curl -X PATCH $API/exams/ex_… -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{ "due_date": "2026-10-02T09:00:00Z" }'
curl -X DELETE $API/exams/ex_… -H "Authorization: Bearer $KEY"

Assignment#

bash
curl -X POST $API/exams/ex_…/assignments -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{ "group_ids": ["grp_a", "grp_b"] }'
curl $API/exams/ex_…/assignments -H "Authorization: Bearer $KEY"
curl -X DELETE $API/exams/ex_…/assignments/grp_b -H "Authorization: Bearer $KEY"

Read#

bash
curl "$API/exams?app=groutcode&status=published&updated_since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $KEY"
curl $API/exams/ex_… -H "Authorization: Bearer $KEY"             # + groups, stats, code_secret_set
curl $API/exams/ex_…/attempts -H "Authorization: Bearer $KEY"    # who started, when, hidden-test release
curl $API/exams/ex_…/scores -H "Authorization: Bearer $KEY"
curl $API/exams/ex_…/analytics -H "Authorization: Bearer $KEY"
curl $API/exams/ex_…/export.csv -H "Authorization: Bearer $KEY" -o results.csv

Events#

exam.published, exam.assigned, exam.attempt_started, exam.submitted, exam.graded.

PreviousGuardiansNextGroutCode Coding Exams