Notification Repository - API Contract

GET /api/v1/notifications/api/v1/notifications

List notifications for a user with pagination

Public

Response Example

{
  "data": [
    {
      "notification_id": "notif-8821",
      "user_id": "usr-441",
      "title": "Assignment Due Tomorrow",
      "body": "Your assignment 'Math Worksheet 3' is due tomorrow at 11:59 PM.",
      "category": "deadline_reminder",
      "is_read": false,
      "deep_link": "/assignments/asgn-991",
      "created_at": "2026-03-25T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47
  }
}

GET /api/v1/notifications/api/v1/notifications/:id

Get a single notification by ID

Public

Response Example

{
  "notification_id": "notif-8821",
  "user_id": "usr-441",
  "title": "Assignment Due Tomorrow",
  "body": "Your assignment 'Math Worksheet 3' is due tomorrow at 11:59 PM.",
  "category": "deadline_reminder",
  "is_read": false,
  "deep_link": "/assignments/asgn-991",
  "created_at": "2026-03-25T14:00:00Z"
}

POST /api/v1/notifications/api/v1/notifications

Save a new notification record

Public

Request Example

{
  "user_id": "usr-441",
  "title": "New Assignment Posted",
  "body": "A new assignment 'Biology Lab Report' has been posted.",
  "category": "assignment_posted",
  "is_read": false,
  "deep_link": "/assignments/asgn-1004"
}

Response Example

{
  "notification_id": "notif-8850",
  "user_id": "usr-441",
  "title": "New Assignment Posted",
  "body": "A new assignment 'Biology Lab Report' has been posted.",
  "category": "assignment_posted",
  "is_read": false,
  "deep_link": "/assignments/asgn-1004",
  "created_at": "2026-03-26T08:12:00Z"
}

PUT /api/v1/notifications/api/v1/notifications/:id

Update a notification (e.g. mark as read)

Public

Request Example

{
  "is_read": true
}

Response Example

{
  "notification_id": "notif-8821",
  "is_read": true,
  "read_at": "2026-03-26T09:00:00Z"
}

DELETE /api/v1/notifications/api/v1/notifications/:id

Delete a notification record

Public

Response Example

{
  "deleted": true,
  "notification_id": "notif-8821"
}

POST /api/v1/notifications/api/v1/notifications/:id/read

Mark a single notification as read

Public

Response Example

{
  "notification_id": "notif-8821",
  "is_read": true,
  "read_at": "2026-03-26T09:00:00Z"
}

POST /api/v1/notifications/api/v1/notifications/read-all

Mark all notifications as read for a user

Public

Request Example

{
  "user_id": "usr-441"
}

Response Example

{
  "updated_count": 12,
  "user_id": "usr-441"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}