# Groups

> Classes and sections. Exams are assigned to groups, not to individual students.

Canonical: https://grout.app/developer/documentation/people/groups/

A group is a named set of students with a faculty owner. Assign an exam to a group and every member sees it in the app; add a student to the group later and they see it too.

## Create

```bash
curl -X POST $API/groups -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "name": "CS101 – Section A",
  "description": "Autumn 2026",
  "faculty_id": "faculty3.4f9a2b1c@grout.user",
  "student_ids": ["u_1", "u_2", "u_3"]
}'
```

`faculty_id` may be an id or login email. Omit it and the institution admin becomes the owner. Unknown or foreign `student_ids` are skipped silently; the response's `member_count` tells you how many landed.

## Membership

```bash
curl -X POST $API/groups/grp_…/members -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{ "student_ids": ["u_4"] }'
curl -X DELETE $API/groups/grp_…/members/u_4 -H "Authorization: Bearer $KEY"
```

`PATCH /groups/{id}` with `student_ids` **replaces** the whole membership — handy for nightly section sync.

## Read

```bash
curl "$API/groups?q=CS101" -H "Authorization: Bearer $KEY"
curl $API/groups/grp_… -H "Authorization: Bearer $KEY"     # members + assigned exams
```

## Mapping LMS sections

Keep a table `lms_section_id → grout_group_id`. On each sync: create missing groups, `PATCH` membership for existing ones, and delete groups whose section was archived. Because exam assignments hang off the group, deleting a group also unassigns its exams — archive instead if results still matter.

## Events

`exam.assigned` fires per group when an exam is assigned.