Mantle2 Notifications Endpoints

User notification management. All notification routes are scoped to a user. There is no top-level /v2/notifications route.

Notification Schema

Notifications inform users about relevant events, updates, and system messages. Each notification contains:

Field	Type	Description	Constraints
id	string	Unique notification identifier (24-digit zero-padded)	Required
user_id	string	ID of user receiving notification (24-digit)	Required
type	string	Notification type/category	Required
title	string	Notification title	Required, max 100
message	string	Notification message text	Required, max 500
source	string	Source system/component	Required
link	string | null	Optional URL for "click to view more"	URI format, optional
read	boolean	Whether user has marked as read	Default: false
created_at	string	ISO 8601 timestamp	Auto-generated

Notification Types

Common notification types include:

• info — General informational notifications
• article — New article available or article-related updates
• event — Event invitations, reminders, or updates
• friend — Friend requests or friendship-related notifications
• prompt — New daily prompts or prompt responses
• system — System announcements or maintenance notices

Notification Sources

• system — Platform-generated notifications
• user — User-initiated notifications (e.g., friend requests)
• automated — Scheduled or trigger-based notifications

Per-User by ID

GET /v2/users/{id}/notifications

List all notifications for a user.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Query Parameters

Name	Type	Description
limit	int	Page size
page	int	Page index
sort	string	Sort expression

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000006789012345",
			"user_id": "000000000000000123456789",
			"type": "article",
			"title": "New Article Published",
			"message": "A new article on circadian rhythms has been published by dr_smith",
			"source": "system",
			"link": "https://earth-app.example.com/articles/000000000000002345678901",
			"read": false,
			"created_at": "2025-01-10T16:00:00Z"
		},
		{
			"id": "000000000000006789012346",
			"user_id": "000000000000000123456789",
			"type": "event",
			"title": "Event Reminder",
			"message": "Community Running Group starts in 2 hours",
			"source": "automated",
			"link": "https://earth-app.example.com/events/000000000000003456789012",
			"read": true,
			"created_at": "2025-01-10T14:00:00Z"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 2
}

401 Unauthorized — authentication required

404 Not Found — user not found

GET /v2/users/{id}/notifications/

Retrieve single notification.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)
notificationId	string	Notification ID (24-digit string)

Responses

200 OK:

{
	"id": "000000000000006789012345",
	"user_id": "000000000000000123456789",
	"type": "article",
	"title": "New Article Published",
	"message": "A new article on circadian rhythms has been published by dr_smith",
	"source": "system",
	"link": "https://earth-app.example.com/articles/000000000000002345678901",
	"read": false,
	"created_at": "2025-01-10T16:00:00Z"
}

401 Unauthorized

404 Not Found

DELETE /v2/users/{id}/notifications/

Delete specific notification.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)
notificationId	string	Notification ID (24-digit string)

Responses

204 No Content — deleted successfully

401 Unauthorized

404 Not Found

POST /v2/users/{id}/notifications/mark_all_read

Mark all notifications as read for user.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Responses

204 No Content — all notifications marked as read

401 Unauthorized

404 Not Found

POST /v2/users/{id}/notifications/mark_all_unread

Mark all notifications as unread for user.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Responses

204 No Content — all notifications marked as unread

401 Unauthorized

404 Not Found

POST /v2/users/{id}/notifications/{notificationId}/mark_read

Mark specific notification as read.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)
notificationId	string	Notification ID (24-digit string)

Responses

204 No Content — notification marked as read

401 Unauthorized

404 Not Found

POST /v2/users/{id}/notifications/{notificationId}/mark_unread

Mark specific notification as unread.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)
notificationId	string	Notification ID (24-digit string)

Responses

204 No Content — notification marked as unread

401 Unauthorized

404 Not Found

DELETE /v2/users/{id}/notifications/clear

Delete all notifications for user.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Responses

204 No Content — all notifications cleared

401 Unauthorized

404 Not Found

Per-User by Username

All endpoints mirror ID-based functionality using username parameter.

GET /v2/users/{username}/notifications

List notifications for user by username.

Path Parameters

Name	Type	Description
username	string	Username

Responses

200 OK — same structure as GET by ID

400 Bad Request

404 Not Found

GET /v2/users/{username}/notifications/

200 OK; 401; 404

Path Parameters

Name	Type	Description
username	string	Username
notificationId	string	Notification ID (24-digit string)

DELETE /v2/users/{username}/notifications/

204; 401; 404

POST /v2/users/{username}/notifications/mark_all_read

204; 401; 404

POST /v2/users/{username}/notifications/mark_all_unread

204; 401; 404

POST /v2/users/{username}/notifications/{notificationId}/mark_read

204; 401; 404

POST /v2/users/{username}/notifications/{notificationId}/mark_unread

204; 401; 404

DELETE /v2/users/{username}/notifications/clear

204; 401; 404

Current User

All endpoints for the currently authenticated user.

GET /v2/users/current/notifications

List notifications for current user.

Responses

200 OK — same structure as GET by ID

401 Unauthorized

GET /v2/users/current/notifications/

200 OK; 401; 404

Path Parameters

Name	Type	Description
notificationId	string	Notification ID (24-digit string)

DELETE /v2/users/current/notifications/

204; 401; 404

POST /v2/users/current/notifications/mark_all_read

204; 401; 404

POST /v2/users/current/notifications/mark_all_unread

204; 401; 404

POST /v2/users/current/notifications/{notificationId}/mark_read

204; 401; 404

POST /v2/users/current/notifications/{notificationId}/mark_unread

204; 401; 404

DELETE /v2/users/current/notifications/clear

204; 401; 404

Notes

• Notifications are scoped to individual users
• The link field is optional and provides a URL for users to navigate to related content
• Notifications can be filtered by type on the client side
• The read status is managed separately per notification
• Bulk operations (mark all read/unread, clear all) provide efficient management

Error Format

{
	"error": {
		"code": "E404",
		"message": "Notification not found"
	}
}