Assignments - API Reference

Audience: Frontend engineers (the admin panel), mobile/portal engineers, backend engineers, QA. Scope: Admin, teacher-portal, student-portal, guardian-portal, and file-download surfaces owned by the Assignments module. 76 routes total (GET /api/subjects/{publicId}/assignments and POST /api/subjects/{publicId}/assignments are owned by the unrelated ClassSubjects module — teacher-to-subject assignment, not homework — and are out of scope here).

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Note on Nest route resolution: AssignmentsController, AssignmentLifecycleController and AssignmentSubmissionsController all share the base path assignments. Static segments (options, preview) are declared before :id in AssignmentsController, and every lifecycle/submissions route has a literal segment after :id (:id/publish, :id/submissions/:rowId), so no controller's route is ever shadowed by another's :id catch-all.

5. Auth, Identity, and Permissions

Every endpoint requires a valid session (JwtAuthGuard is global with no @Public() opt-out anywhere in this module). No guest/anonymous access exists on any assignments route.

6. DTO and Model Reference

6.1 AssignmentCreateBaseDto (shared by AdminCreateAssignmentDto and TeacherCreateAssignmentDto)

AdminCreateAssignmentDto adds one field:

TeacherCreateAssignmentDto adds no fields — teacherId is implicitly the caller and forbidNonWhitelisted (global ValidationPipe) rejects the field if sent.

6.1a AdminUpdateAssignmentDto / TeacherUpdateAssignmentDto

Both are the same class body (AssignmentUpdateBaseDto, authoring/core/dto/update-assignment.dto.ts:47); neither accepts teacherId — PUT :id/teacher is the only writer of that column. Every field is optional except version; a field that is absent keeps the stored value.

The update service overlays the request on the locked row and validates the merged result (validateMergedAssignmentFields, assignment-merge-validation.util.ts:79-188) before writing. That is where the cross-field codes come from:

6.2 AssignmentDetailDto (response — admin/teacher detail)

6.3 AssignmentFileDto

6.4 AssignmentLinkInputDto

6.5 SaveDraftDto / SubmitAssignmentDto (pupil submission)

6.6 SaveReviewDto / CompleteReviewDto / ReturnSubmissionDto

6.7 AssignmentAudiencePreviewRequestDto / AssignmentAudiencePreviewDto

Request: { academicSessionId: uuid; subjectId: uuid; classSubjectIds: uuid[] } (same shape/limits as the create DTO's targeting fields). Response: { totalPupils: number; byClass: { classSubjectId, className, pupilCount }[] } — a read-only projection, no persistence.

6.8 ListAssignmentsQueryDto / ListAssignmentSubmissionsQueryDto / ListStudentAssignmentsQueryDto

All extend the shared QueryDto (page, size, pagination, sort, search). Assignment-specific additions:

6.9 AssignmentTransferReviewDto / ResolveTransferReviewDto

ResolveTransferReviewDto (request body for POST :id/resolve): resolution ("keep" | "not_applicable", required) and note (string, optional, ≤500 chars).

7. Enum Reference

8. Endpoint Reference

The endpoints below are grouped by capability; every route from §4 is covered either here in full detail or, for the many structurally-identical lifecycle/CRUD siblings, in the route-by-route matrix in §13.1. Every admin route has an exact teacher-portal mirror with the same request/response shape and no @Permissions(); rather than repeat each pair twice, the teacher-portal differences are called out inline where the behavior differs (scope, not shape).

8.1 POST /api/assignments (and POST /api/mobile/teacher/assignments)

Purpose

Creates a new assignment, always as a draft. Used by the admin panel's and the teacher portal's assignment-creation form. The admin route accepts an optional teacherId; the teacher route always uses the caller as the teacher and rejects the field if sent.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: Assignments_CREATE (admin route only; teacher route carries none — resolveTeacher is the control).
• Guest support: none.
• Rate limit: none on this route (upload routes are throttled; this is JSON-only).
• Idempotency: clientRequestId, unique per (createdByUserId, clientRequestId). Both the admin and the teacher route answer 201 with "Assignment created." for a genuine insert and 200 with "Assignment already created." when a replay returns the existing assignment.

Request

{
  "academicSessionId": "01973a...",
  "subjectId": "01973b...",
  "title": "Algebra worksheet 4",
  "classSubjectIds": ["01973c..."],
  "dueAt": "2026-09-22T10:00:00.000Z"
}

Full request with optional fields:

{
  "clientRequestId": "01973d...",
  "academicSessionId": "01973a...",
  "subjectId": "01973b...",
  "categoryId": "01973e...",
  "title": "Algebra worksheet 4",
  "instructionsHtml": "<p>Complete exercises 1-10.</p>",
  "classSubjectIds": ["01973c...", "01973f..."],
  "links": [{ "label": "Reference", "url": "https://example.com/ref" }],
  "dueAt": "2026-09-22T10:00:00.000Z",
  "latePolicy": "until_final_deadline",
  "finalDeadlineAt": "2026-09-24T10:00:00.000Z",
  "allowTextResponse": true,
  "allowFileUpload": true,
  "maxFiles": 3,
  "submissionFileTypes": ["pdf", "docx"],
  "resubmissionPolicy": "limited",
  "maxAttempts": 3,
  "isGraded": true,
  "maxMarks": 20,
  "passMarks": 10,
  "marksRelease": "manual",
  "teacherId": "01973g..."
}

Response

Both routes: 201 with "Assignment created." on genuine creation, 200 with "Assignment already created." when a clientRequestId replay returned the existing row.

{
  "success": true,
  "message": "Assignment created.",
  "data": {
    "id": "01973h...",
    "status": "draft",
    "displayStatus": "draft",
    "version": "0"
  }
}

(Full shape: AssignmentDetailDto, §6.2.)

Side Effects

• Database writes: assignments (insert), assignment_classes (one row per target).
• Cache: none.
• BullMQ jobs: none.
• Realtime events: none.
• Notifications: none (a draft is invisible to anyone but its author/managers).
• Audit logs: ActivityAuditInterceptor records the mutating request; assignment_history gets a created entry.
• External API calls: none.

Error Cases

Edge Cases

• Empty classSubjectIds: allowed at create (a draft may have zero targets); publishing without any is blocked separately (ASSIGNMENT_NO_CLASSES).
• Duplicate class-subject in the array: rejected (422).
• Replayed clientRequestId: idempotent, 200, no second row.
• Cross-field rules on create. AssignmentWriteService.create builds the merged field set as a draft with dueAtChanged: false and publishAt: null and runs it through the same validateMergedAssignmentFields that PATCH uses (authoring/core/assignment-write.service.ts:211-215), before the insert. A body that breaks one of those rules — finalDeadlineAt without latePolicy='until_final_deadline', both submission methods off, or isGraded: true without maxMarks — returns the same named 400 code create-time as it does on update: ASSIGNMENT_FINAL_DEADLINE_INVALID, ASSIGNMENT_SUBMISSION_SETTINGS_INVALID, or ASSIGNMENT_GRADING_INVALID (§12). The due-date lead-time check (ASSIGNMENT_DUE_IN_PAST/ASSIGNMENT_PUBLISH_AT_INVALID) is not part of this call — a draft's due date is only checked when it is later published or scheduled.

Example Requests

POST /api/assignments HTTP/1.1
Authorization: Bearer TOKEN
Content-Type: application/json

curl -X POST "$API_URL/api/assignments" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"academicSessionId":"...","subjectId":"...","title":"Algebra worksheet 4","classSubjectIds":["..."],"dueAt":"2026-09-22T10:00:00.000Z"}'

8.2 POST /api/assignments/:id/publish (and teacher mirror)

Purpose

Publishes an assignment immediately, or schedules a future publish. Publishing now materialises the pupil roster and notifies; scheduling defers both to the publish-due sweep.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AssignmentPublish_CREATE (admin); none (audience) for teacher.
• Guest support: none.
• Rate limit: none.
• Idempotency: calling publish-now again on an already-published assignment, or schedule again with the same publishAt, is a no-op returning the current detail. The already-in-target-state check runs before the version check, so this no-op succeeds even with a stale version — every other lifecycle route (unschedule, close, reopen, cancel, archive, unarchive) follows the same ordering, which is what makes a double-click safe rather than a race to a 409.

Request

{ "version": "0", "mode": "now" }

or

{ "version": "0", "mode": "schedule", "publishAt": "2026-09-20T06:00:00.000Z" }

Response

200 with AssignmentDetailDto, status now published or scheduled.

Side Effects

• Database writes: assignments (status/publish fields), assignment_students (insert, publish-now only), assignment_history (published/scheduled).
• Jobs: none directly (the sweep that later publishes a scheduled assignment is cron-driven, not enqueued here).
• Notifications: published event to newly-materialised pupils and their guardians (publish-now only).

Error Cases

The guards run in the order listed and stop at the first failure. The publish-due sweep re-runs the same guards; a failure there does not reach any HTTP caller — the assignment returns to draft and the creator receives a publish_failed notification.

Edge Cases

• Already published (mode now): no-op, 200, unchanged detail.
• Already scheduled at the same publishAt (mode schedule): no-op.
• The scheduled sweep itself hits the same guard set at fire time; a failure there reverts to draft rather than returning an error to any caller (no caller is waiting — it is a background tick).

8.3 PUT /api/mobile/student/assignments/:id/submission/submit

Purpose

Submits the pupil's current work — text and/or previously-attached files — for review. Called after the pupil has saved a draft and/or attached files, or directly for a files-less first submit.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard, IpThrottlerGuard.
• Permission: none — resolveStudent is the control.
• Guest support: none.
• Rate limit: RATE_LIMITS.CUSTOMER_WRITE.
• Idempotency: clientSubmissionId; a replay matching the current latest non-draft attempt is a no-op success.

Request

{ "clientSubmissionId": "01973i...", "textHtml": "<p>My answer...</p>" }

Minimal (files-only, no draft yet):

{ "clientSubmissionId": "01973i...", "textHtml": null }

Response

200 with the pupil's StudentAssignmentDetailDto (own record + attempt history), re-read after commit.

Side Effects

• Database writes: prior pending attempt (if any) → superseded; target attempt → submitted; assignment_students counters/state; assignment_history (submitted).
• Notifications: submitted to the pupil (confirmation), guardians (low priority), and the teacher.

Error Cases

Edge Cases

• Submitting with no draft and no files, only textHtml: allowed — creates the first attempt directly.
• Every attached file rejected and no text: treated specially — this is ASSIGNMENT_SUBMISSION_EMPTY only if it is also the FIRST submission; if it is a resubmission scenario the content-rejection logic (pendingContentRejectedSql) instead grants an extra chance to fix it.
• Class removed since assignment: window closes even mid-composition; submit answers 409 ASSIGNMENT_NOT_ACCEPTING.
• Save draft, file upload/removal and submit all run the same two checks in the same order — resolve the pupil, then assertNotGraduatedReadOnly — so a graduated pupil's session and file routes on this controller answer the same 403 STUDENT_GRADUATED_READ_ONLY as submit.

8.4 PUT /api/assignments/:id/submissions/:rowId/review (and teacher mirror), POST .../complete, POST .../return

Purpose

The three review actions a teacher/admin takes on one pupil's latest attempt: hold marks/feedback privately (review), finalise and release per policy (complete), or send back for another try (return).

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AssignmentReview_UPDATE (admin); none (teacher, scoped by reviewRow).
• Rate limit: none.
• Idempotency: none beyond the version optimistic check — a duplicate call with a stale version is rejected, not silently accepted.

Request (all three share attemptId + version)

{ "attemptId": "01973j...", "version": "0", "marks": 15, "grade": "A", "feedbackHtml": "<p>Good work.</p>" }

Return requires feedbackHtml and accepts an optional deadline:

{ "attemptId": "01973j...", "version": "1", "feedbackHtml": "<p>Please redo question 3.</p>", "resubmitDueAt": "2026-09-25T10:00:00.000Z" }

Response

200 with AssignmentSubmissionRecordDto — the full pupil record including attempt history.

Side Effects

• review: attempt/row → under_review; history review_saved; no notification (nothing pupil-visible yet).
• complete: attempt/row → completed, finalMarks/finalGrade set; result_published_at set immediately when marksRelease='on_review' or the assignment already has a marksReleasedAt from an earlier bulk release; history completed; marked notification iff visible immediately.
• return: attempt → returned, row → returned, result cleared, resubmit_due_at set/cleared, extra_attempts_granted incremented (unless policy unlimited); history returned; returned notification.

Error Cases

Edge Cases

• return on an assignment that is only closed (not published): rejected — returnSubmission requires strictly published, unlike review/complete which also accept closed.
• complete with marksRelease='manual' and no prior release on this assignment: the mark is saved but held; a subsequent POST :id/release-marks is required to make it visible. Once that release has happened once, every later complete on the same assignment publishes immediately regardless of the policy.
• return when the pupil is already at the extra-attempt ceiling (policy not unlimited and extraAttemptsGranted >= ASSIGNMENT_MAX_EXTRA_ATTEMPTS): 409 ASSIGNMENT_RESUBMISSION_NOT_ALLOWED, same code the pupil's own submit uses at the attempt ceiling.
• Visibility is checked before status: an assignment outside the reviewer's visibleAssignment scope is 404 ASSIGNMENT_NOT_FOUND even when the row/attempt would otherwise be a valid target — a reviewer never learns an out-of-scope assignment's current status from the shape of the error.
• Reviewing an attempt superseded by a newer submission mid-review: 409 ASSIGNMENT_ATTEMPT_NOT_REVIEWABLE.

8.5 File download — GET .../assignment-files/:fileId (all four audiences)

Purpose

Streams a file's bytes: an assignment attachment (any audience whose scope covers the assignment) or a pupil's own submitted file (teacher review, or the pupil themselves — never a guardian, and never a pupil's still-draft attempt even for staff: a submission-file lookup explicitly excludes status='draft').

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard, IpThrottlerGuard (RATE_LIMITS.UPLOAD_READ).
• Permission: Assignments_READ (admin only); none (portal, scoped by actor kind + file kind).
• Guardian scope: attachments only — a submission file filePublicId for a guardian actor is refused as 404, not a kind-mismatch error, so the response gives no signal about whether the id even exists.

Response

Not a JSON envelope — a binary stream. setAssignmentFileDownloadHeaders (files/assignment-file-download-headers.ts:21-27) sets Content-Type (the stored MIME), X-Content-Type-Options: nosniff, Cache-Control: private, no-store, Content-Security-Policy: sandbox; default-src 'none', Content-Length, and Content-Disposition. Error responses before the stream starts use the normal JSON error envelope.

Error Cases

Scope is checked before scan status, so an id the caller may not see is always 404, whatever its status.

Edge Cases

• Requesting a pending file mid-scan: 409 ASSIGNMENT_FILE_NOT_READY, retry shortly.
• Requesting a rejected file: 410 — rejected bytes are retained for the quarantine window but never streamed to anyone, including an administrator.

8.6 File upload and removal — attachments and submission files

Routes: POST /api/assignments/:id/attachments, DELETE /api/assignments/:id/attachments/:fileId, their teacher mirrors under /api/mobile/teacher/assignments/:id/attachments*, and the pupil's POST /api/mobile/student/assignments/:id/submission/files and DELETE /api/mobile/student/assignments/:id/submission/files/:fileId.

Request

multipart/form-data with one file part and an optional clientUploadId (uuid) field. Replaying the same clientUploadId from the same uploader returns the file already recorded, as long as it belongs to the same assignment (or the same pupil draft) — including when two requests race: the losing insert hits the clientUploadId unique index, and the loser then looks up and returns the winner's row instead of erroring. The uploaded filename is re-decoded as UTF-8 where the raw bytes support it, stripped of control and bidirectional-control characters, and capped at 255 code points before it is stored — never trusted verbatim. Each upload type stages bytes under its own private prefix (uploads/assignment-attachment/staging, uploads/assignment-submission/staging); the generic GET /api/upload/file/* route refuses any key under either prefix with 404 UPLOAD_FILE_KEY_INVALID, so an assignment file is only ever reachable through this module's own download endpoints.

Validation order

Checks run in this order and stop at the first failure (files/assignment-file-upload-attachment.ts:123-141, files/assignment-file-upload-submission.ts:148-166):

1. The assignment is visible (and, for attachments, manageable) to the caller.
2. (Submission only) allowFileUpload is on.
3. The extension maps to a known file type.
4. The file is not empty.
5. The file is within assignment_settings.max_file_size_mb.
6. The type is in assignment_settings.attachment_file_types (attachments) or the assignment's submission_file_types (submission files).
7. The uploader has fewer than 20 files still pending a scan (checked once outside the transaction, then re-checked inside it under a per-uploader pg_advisory_xact_lock so two concurrent uploads from the same person cannot both slip past the outer check).
8. The storage layer accepts the bytes and sniffs their MIME; the sniffed MIME must match what the declared file type requires (a fixed MIME for txt/csv) or the upload is purged and refused as a security-check failure, even though it already passed the extension/size/allowlist checks above.
9. Inside the write transaction: the attachment count, or the pupil draft's file count and total bytes (summed over non-superseded attempts only — a superseded attempt's files stop counting the moment a newer attempt replaces it), is still within its limit.

Error Cases

A file accepted here is only the start: its scan verdict arrives later. A file that is later rejected blocks publishing (ASSIGNMENT_HAS_REJECTED_ATTACHMENTS) or submitting (ASSIGNMENT_SUBMISSION_HAS_REJECTED_FILES) until it is removed, and its download answers 410 ASSIGNMENT_FILE_REJECTED.

8.7 PATCH /api/assignments/:id (and PATCH /api/mobile/teacher/assignments/:id)

Purpose

Edits an assignment. The request shape and the per-status restrictions are in §6.1a.

Auth and Permissions

• Permission: Assignments_UPDATE (admin); none for the teacher mirror, which is scoped by the manage predicate.
• Idempotency: version optimistic concurrency.

Error Cases

8.8 Remaining route families — error cases

The routes below reuse the DTOs in §6 and are listed with every error code they can return.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (representative: submit)

9.3 Error Branch (representative: lifecycle action)

10. Pagination, Sorting, Filtering, and Search

All list/roster/history endpoints use the shared PaginationUtil (common/utils/pagination.util.ts) — offset pagination, {count, page, size} metadata envelope, no hand-rolled offset math anywhere in this module. The admin/teacher assignment list orders by the requested sort column in the requested direction with NULLS LAST, then by assignments.id as a tiebreaker — so two rows with an equal or null value on the sort column, or a page boundary landing between them, always resolve in a stable, repeatable order.

11. Caching, Jobs, and External Integrations

12. Error Code Reference

Every ASSIGNMENT_* code in apps/api/src/common/types/error-codes.ts (lines 1494-1562), with the HTTP status it is returned with, the routes that can return it, and what a consumer should do. Paths in the Source column are relative to apps/api/src/modules/assignments/. "Admin and teacher" means the admin route and its /api/mobile/teacher mirror.

Three codes are never returned over HTTP — ASSIGNMENT_FILE_PURGE_FAILED and ASSIGNMENT_FILE_SCAN_WORKER_FAILED are written to the server log only, and ASSIGNMENT_SETTINGS_INVALID is defined but not referenced anywhere. They are listed at the end of this table and described in the backend doc §13.

Generic codes owned by other modules also appear on these routes: 400 validation errors from the global ValidationPipe, 400 PAGINATION_LIMIT_INVALID on the lists that refuse pagination=false (§10), 404 SUBJECT_NOT_FOUND and 404 ACADEMIC_SESSION_NOT_FOUND on create and update, 401/403 from the guards, and 429 from IpThrottlerGuard on throttled routes.

Two more shared codes cover every write under a locked academic session or a graduated pupil, on every table this module owns — assignments, assignment_classes, assignment_students, assignment_submission_attempts, assignment_links, and assignment_files for insert and delete (not update, so a pending scan can still finish after a lock):

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered per-endpoint in §8 for the representative routes (create, publish, submit, review actions, download) and via the shared DTO tables in §6 for every other route, since the remaining lifecycle/CRUD/settings routes reuse those exact shapes. Every route's success envelope follows the repo-standard {success, message, data} (or {success, message, data, meta} for paginated lists) via ResponseDto/ApiPaginatedResponseDto.

13.3 API Diagram Pack

Covered in §9. Additional cache/async-flow diagrams are unnecessary here: this module has no cache layer (§11), and the one async flow (file scan) is diagrammed in the backend doc §7.4.

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4 surface map + §13.1 completeness matrix — all 76 in-scope routes).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, nested field, enum, default, and validator is documented (§6, §7).
• Every response field is documented for the representative DTOs (§6.2–6.7); list/roster DTOs reuse the same field vocabulary.
• Every auth, guard, permission, and guest-identity branch is documented (§5).
• Every success, validation, auth, permission, not-found, conflict, and rate-limit branch is documented (§8, §13.1).
• Every database read/write, queue job, and notification path is documented (§8 side effects, backend doc §9).
• Representative routes have minimal/full/success/failure examples (§8.1–8.5); the remaining routes share those exact shapes per §6.
• Route, sequence, and error diagrams are included (§9).
• Tradeoffs and compatibility risk are documented (§13.5, §13.6).
• This doc links to backend and features/flows.

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented (§7).
• Every response envelope is documented.
• Every error code is documented (all 62 ASSIGNMENT_* codes in §12, with per-route lists in §8; the registry is apps/api/src/common/types/error-codes.ts:1494-1562).
• Every auth guard and permission is documented.
• Every cache key (none), queue job, and external call is documented (§11).
• Every diagram matches the current code.
• This doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/assignments/backend
• Features and flows doc: /docs/developer/assignments/feature