Overview The Notifications API allows you to retrieve and manage notifications that are automatically generated when certain household activities occur (completing chores, paying bills, etc.).
Endpoints Get All Notifications Retrieves all notifications for the authenticated user’s household, ordered by most recent first.
Authentication : RequiredResponse Array of notification objects
Show Notification Object Fields
ID of the household this notification belongs to
Notification type: “chores”, “bills”, “shopping”, “maintenance”
Notification message body
Whether the notification has been read (default: false)
When the notification was created
curl -X GET https://your-domain.com/api/notifications \ -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response [ { "id" : "clxnot1" , "householdId" : "clx456def" , "type" : "chores" , "title" : "Chore Completed" , "body" : "You completed: Vacuum living room" , "read" : false , "createdAt" : "2024-03-15T14:30:00Z" }, { "id" : "clxnot2" , "householdId" : "clx456def" , "type" : "bills" , "title" : "Bill Paid" , "body" : "You paid: Electric Bill for $125.50" , "read" : true , "createdAt" : "2024-03-15T10:15:00Z" }, { "id" : "clxnot3" , "householdId" : "clx456def" , "type" : "shopping" , "title" : "Item Removed" , "body" : "You completed: Milk" , "read" : false , "createdAt" : "2024-03-15T09:45:00Z" }, { "id" : "clxnot4" , "householdId" : "clx456def" , "type" : "maintenance" , "title" : "Maintenance Completed" , "body" : "Task completed: Replace air filter" , "read" : true , "createdAt" : "2024-03-14T16:20:00Z" } ]
Delete Notification POST /api/notifications/delete
Deletes a specific notification.
Authentication : RequiredRequest Body curl -X POST https://your-domain.com/api/notifications/delete \ -H "Authorization: Bearer YOUR_CLERK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id": "clxnot1"}'
Response { "message" : "Notification deleted" }
Clear All Notifications POST /api/notifications/clear
Deletes all notifications for the authenticated user’s household.
Authentication : Requiredcurl -X POST https://your-domain.com/api/notifications/clear \ -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Response { "message" : "Notifications cleared" }
Automatic Notification Creation Notifications are automatically created when certain actions occur:
Chores When a chore is deleted via POST /api/chores/delete:
Type : “chores”Title : “Chore Completed”Body : “You completed: [chore name]“
Bills When a bill is deleted via POST /api/bills/delete:
Type : “bills”Title : “Bill Paid”Body : “You paid: [bill name] for $[amount]“
When a shopping item is deleted via POST /api/shopping/delete:
Type : “shopping”Title : “Item Removed”Body : “You completed: [item name]“
Maintenance When a maintenance item is deleted via POST /api/maintenance/delete:
Type : “maintenance”Title : “Maintenance Completed”Body : “Task completed: [title]“
Notification Library The API uses the createNotification function from ~/workspace/source/src/app/lib/notifications:
await createNotification ({ householdId: household . id , type: 'chores' , title: 'Chore Completed' , body: `You completed: ${ deleted . name } ` , });
Error Responses User is not authenticated
{ "message" : "Notification ID is required" }
500 Internal Server Error
Unexpected server error
Use Cases Display Unread Notifications const response = await fetch ( '/api/notifications' ); const notifications = await response . json (); const unread = notifications . filter ( n => ! n . read );
Show Recent Activity const response = await fetch ( '/api/notifications' ); const notifications = await response . json (); const recent = notifications . slice ( 0 , 5 ); // Last 5 notifications
Notification Bell Badge const response = await fetch ( '/api/notifications' ); const notifications = await response . json (); const unreadCount = notifications . filter ( n => ! n . read ). length ; // Display unreadCount in badge
Source Code Reference
Get notifications: ~/workspace/source/src/app/api/notifications/route.ts:19
Delete notification: ~/workspace/source/src/app/api/notifications/delete/route.ts:19
Clear all: ~/workspace/source/src/app/api/notifications/clear/route.ts:19
Notification library: ~/workspace/source/src/app/lib/notifications