Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vruizz22/innova-backend-serverless/llms.txt

Use this file to discover all available pages before exploring further.

The Alerts API surfaces issues that the alertGenerator Lambda detects hourly from mastery data — such as students whose pKnown is dropping or consistently stuck below threshold. Teachers can also create alerts manually (e.g. after a classroom observation) and mark them resolved once the issue has been addressed. All active alerts have resolvedAt: null; only unresolved alerts are returned by the list endpoint.

​
Endpoints

​
GET /alerts

List active (unresolved) alerts. Filter by courseId or its alias classroomId. Returns records ordered by createdAt descending. Authentication: JWT required
​
courseId
string
UUID of the course to list alerts for.
​
classroomId
string
Alias for courseId — accepted for backward compatibility with older client versions.
curl "https://api.example.com/alerts?courseId=course-uuid-here" \
  -H "Authorization: Bearer <token>"
Example response: 
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "alertType": "LOW_MASTERY",
    "severity": "HIGH",
    "teacherId": "teacher-uuid",
    "courseId": "course-uuid",
    "topicId": "topic-uuid",
    "studentId": "student-uuid",
    "payload": { "pKnown": 0.15, "attemptsCount": 8 },
    "createdAt": "2024-01-15T10:00:00.000Z",
    "resolvedAt": null
  }
]
​
id
string
Alert UUID.
​
alertType
string
Type code — see Alert types below.
​
severity
string
LOW, MED, or HIGH.
​
teacherId
string
UUID of the teacher who owns the alert.
​
courseId
string
UUID of the course the alert belongs to.
​
topicId
string | null
UUID of the topic associated with the alert, if applicable.
​
studentId
string | null
UUID of the student the alert concerns, if applicable.
​
payload
object
Arbitrary diagnostic data — shape depends on alertType. Common keys: pKnown (float), attemptsCount (int).
​
createdAt
string
ISO 8601 creation timestamp.
​
resolvedAt
string | null
ISO 8601 resolution timestamp, or null if still active.

​
POST /alerts

Create an alert manually. Useful when a teacher notices a pattern during class that hasn’t yet triggered an automated alert. Authentication: JWT required
​
courseId
string
required
UUID of the course this alert belongs to.
​
teacherId
string
required
UUID of the teacher creating the alert.
​
alertType
string
required
Alert type code (e.g. LOW_MASTERY, HIGH_ERROR_RATE).
​
topicId
string
UUID of the topic the alert concerns. Optional.
​
studentId
string
UUID of the student the alert concerns. Optional — omit for class-wide alerts.
​
severity
string
LOW, MED, or HIGH. Defaults to MED if omitted.
​
payload
object
Arbitrary JSON payload for diagnostic context. Optional.
curl -X POST https://api.example.com/alerts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "courseId": "course-uuid",
    "teacherId": "teacher-uuid",
    "alertType": "HIGH_ERROR_RATE",
    "topicId": "topic-uuid",
    "studentId": "student-uuid",
    "severity": "HIGH",
    "payload": { "errorRate": 0.72, "dominantCode": "ARITH_SUB_BORROW_OMITTED_TENS_G3" }
  }'
Response: 201 Created — the created AlertView object.

​
PATCH /alerts/:id/resolve

Mark an alert as resolved. Sets resolvedAt to the current timestamp. The alert will no longer appear in GET /alerts responses. Authentication: JWT required
​
id
string
required
UUID of the alert to resolve.
curl -X PATCH https://api.example.com/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve \
  -H "Authorization: Bearer <token>"
​
id
string
Alert UUID.
​
resolvedAt
string
ISO 8601 timestamp at which the alert was resolved.
Resolving an alert is idempotent from a data-safety standpoint — calling this endpoint on an already-resolved alert will update resolvedAt again. If you need idempotent resolving, check resolvedAt before calling.

​
Alert types

alertTypeDescription
LOW_MASTERYStudent’s pKnown for a topic has dropped below the low-mastery threshold (typically < 0.40).
DECLINING_MASTERYStudent’s pKnown shows a sustained downward trend over recent sessions.
HIGH_ERROR_RATEA specific error code is appearing at an unusually high rate for a student or class.
STUCK_STUDENTStudent has made many attempts on a topic without improvement — may need direct intervention.
alertType is an open string field — integrating systems or teacher-authored alerts can use custom types beyond this list. The four above are the canonical types generated by the alertGenerator Lambda.

​
Auto-generation

The alertGenerator Lambda runs on an hourly schedule (driven by the SQS_HOURLY_ALERTS_URL queue). On each run it:
  1. Scans StudentTopicMastery records for all active enrollments.
  2. Computes pKnown trajectories and compares them against configured thresholds.
  3. Creates TeacherAlert records when a threshold is breached — one alert per (student, topic, alertType) combination to avoid duplicates.
  4. Skips students who already have an unresolved alert of the same type for the same topic.
The Lambda is controlled by the hourlyAlertsEnabled flag visible in GET /admin/status. Unlike the grader and classifier, this killswitch is always reported as true (there is no SSM parameter to pause it independently).
If you are building a teacher dashboard, poll GET /alerts?courseId=<id> every few minutes or use a WebSocket subscription rather than relying solely on the hourly Lambda. Teachers can create urgent alerts at any time via POST /alerts.

Build docs developers (and LLMs) love

Get started for freeTalk to us