Assessments

Manage exams, tests, and continuous assessments. Upload and download score sheets.

All endpoints require Authorization: Bearer <token>. Some require X-SCHOOL-ID.

---

List Assessments

GET /assessments

Returns a paginated list of assessments filtered by cohort, subject, and term.

Query Parameters

Parameter	Type	Required	Default	Description
pageNumber	integer	Yes	0	Zero-indexed page
pageSize	integer	Yes	50	Results per page
cohort	uuid	Yes	—	Cohort batch ID
subject	uuid	Yes	—	Subject ID
term	uuid	Yes	—	Term ID

Example

curl -X GET "https://api.vanillatots.com/assessments?cohort=uuid&subject=uuid&term=uuid" \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "page_number": 0,
  "page_size": 50,
  "total_pages": 1,
  "total": 5,
  "data": [
    {
      "id": "uuid",
      "subject": "uuid",
      "name": "First CA Test",
      "abbreviation": "CA1",
      "due_date": "2024-10-15",
      "total_points": 20.0,
      "term": "uuid",
      "include_in_final": true,
      "publish_scores": false,
      "category": "CA1",
      "file_name": "ca1_math.xlsx"
    }
  ]
}

---

Create Assessment

POST /assessments

Create a new assessment (exam, CA test, etc.).

Request Body

Field	Type	Required	Description
category	enum	Yes	One of: CA1, CA2, CA3, EXAM, FIRST_TERM, SECOND_TERM, THIRD_TERM
subject	uuid	Yes	Subject ID
name	string	Yes	Assessment name
abbreviation	string	Yes	Short code
due_date	date	Yes	Due date (YYYY-MM-DD)
total_points	number	Yes	Maximum score
term	uuid	Yes	Term ID
description	string	Yes	Description
file_name	string	Yes	Associated file name
include_in_final	boolean	Yes	Include in final grade calculation
publish_scores	boolean	Yes	Whether scores are published

Response 200 OK — Returns the created AssessmentResponse.

---

Get Assessment

GET /assessments/{id}

Retrieve a single assessment by ID.

Path Parameters

Parameter	Type	Description
id	uuid	Assessment ID

Response 200 OK — Returns an AssessmentResponse.

---

Delete Assessment

DELETE /assessments/{id}

Remove an assessment.

Path Parameters

Parameter	Type	Description
id	uuid	Assessment ID

Response 200 OK

---

Download Score Sheet

GET /assessments/{id}/download-sheet

Download the score sheet for an assessment as a binary file.

Path Parameters

Parameter	Type	Description
id	uuid	Assessment ID

Example

curl -X GET https://api.vanillatots.com/assessments/{id}/download-sheet \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -o scoresheet.xlsx

Response 200 OK — Returns binary file content (application/octet-stream).

---

Upload Score Sheet

POST /assessments/{id}/scoresheet

Upload a score sheet file for an assessment.

Path Parameters

Parameter	Type	Description
id	uuid	Assessment ID

Request Body — multipart/form-data

Field	Type	Required	Description
scoresheet	binary	Yes	Score sheet file

Example

curl -X POST https://api.vanillatots.com/assessments/{id}/scoresheet \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -F "scoresheet=@/path/to/scoresheet.xlsx"

Response 200 OK