Cohorts

Manage cohort groups (a classroom assigned to a specific academic session), student enrollment, and class composition.

All endpoints require Authorization: Bearer <token> and X-SCHOOL-ID headers unless noted otherwise.

---

List Cohorts

GET /cohorts

Returns all cohorts for the current school.

Example

curl -X GET https://api.vanillatots.com/cohorts \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID"

Response 200 OK

[
  {
    "id": "uuid",
    "classroom": "JSS 1A",
    "session": "2024/2025"
  }
]

---

Create Cohort

POST /cohorts

Create a new cohort by assigning a classroom to an academic session.

Request Body

Field	Type	Required	Description
classroom	uuid	Yes	Classroom ID
session_id	string	Yes	Academic session identifier

Example

curl -X POST https://api.vanillatots.com/cohorts \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "classroom": "classroom-uuid",
    "session_id": "2024/2025"
  }'

Response 200 OK — Returns the created CohortResponse.

---

Get Cohort

GET /cohorts/{id}

Retrieve a single cohort by ID.

Path Parameters

Parameter	Type	Description
id	uuid	Cohort ID

Response 200 OK — Returns a CohortResponse object.

---

Update Cohort

PATCH /cohorts/{id}

Update cohort details (classroom or session assignment).

Path Parameters

Parameter	Type	Description
id	uuid	Cohort ID

Request Body

Field	Type	Required	Description
classroom	uuid	Yes	Classroom ID
session_id	string	Yes	Academic session identifier

Response 200 OK — Returns the updated CohortResponse.

---

Enroll Students

POST /cohorts/{id}/enrollment

Enroll one or more students into a cohort.

Path Parameters

Parameter	Type	Description
id	uuid	Cohort ID

Request Body

Field	Type	Required	Description
students	uuid[]	Yes	Array of student IDs (min 1)
batch	uuid	Yes	Batch ID for enrollment

Example

curl -X POST https://api.vanillatots.com/cohorts/{id}/enrollment \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "students": ["student-uuid-1", "student-uuid-2"],
    "batch": "batch-uuid"
  }'

Response 200 OK — Returns an array of enrolled StudentResponse objects.

---

List Cohort Students

GET /cohorts/{id}/students

Get all students enrolled in a specific cohort.

Path Parameters

Parameter	Type	Description
id	uuid	Cohort ID

Example

curl -X GET https://api.vanillatots.com/cohorts/{id}/students \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID"

Response 200 OK — Returns an array of StudentResponse objects.

---

Remove Students from Cohort

PATCH /cohorts/{cohortId}/remove_students

Remove one or more students from a cohort.

Path Parameters

Parameter	Type	Description
cohortId	uuid	Cohort ID

Request Body

Field	Type	Required	Description
student_ids	uuid[]	Yes	Array of student IDs to remove (min 1)

Example

curl -X PATCH https://api.vanillatots.com/cohorts/{cohortId}/remove_students \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_ids": ["student-uuid-1", "student-uuid-2"]
  }'

Response 200 OK — Returns the remaining StudentResponse array.