# Exams Overview

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

Canonical: https://grout.app/developer/documentation/exams/overview/

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": "faculty3.4f9a2b1c@grout.user",
  "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_…"]
}'
```

| Field | Notes |
|---|---|
| `faculty_id` | Required. Id or login email of the owning teacher. |
| `exam_type` | `exam`, `homework`, `assignment`, `quiz`, `project` |
| `time_limit_minutes` | Starts a countdown when the student opens the exam. |
| `proctoring` | What the student must enable before the exam opens. See [Proctoring & AI Policy](/developer/documentation/exams/proctoring/). |
| `ai_policy` | Rules for the in-app assistant. |
| `code_spec` | Present ⇒ GroutCode coding exam. See [GroutCode Coding Exams](/developer/documentation/exams/groutcode/). |
| `publish` | Default `true`. Pass `false` to keep a draft. |
| `group_ids` | Assign 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`.