Notifications

Broadcast Notification

Endpoint: POST /notifications/broadcast

Description: Broadcast notification to all active users. (Admin only)

Request Body:

{
    "notification_type": "new_feature",
    "title": "New Feature Alert!",
    "body": "We've just launched a new feature!",
    "data": {},
    "channels": ["email", "push"],
    "priority": "high",
    "target": "all_users"
}

Response: 202 Accepted

{
    "message": "Broadcast queued for processing. Track with ID: broadcast_uuid",
    "id": "broadcast_uuid"
}

Delete Notification

Endpoint: DELETE /notifications/{notification_id}

Description: Delete a notification.

Response: 200 OK

{
    "message": "Notification deleted successfully",
    "id": "notification_uuid"
}

Register Device Token

Endpoint: POST /notifications/device-token

Description: Register a device for push notifications.

Request Body:

{
    "fcm_token": "fcm_token",
    "device_type": "android",
    "device_name": "Pixel 7",
    "device_model": "Pixel 7",
    "app_version": "1.0.0"
}

Response: 201 Created

{
    "id": "device_uuid",
    "user_id": "user_uuid",
    "device_type": "android",
    "is_active": true,
    "last_used_at": "2025-11-27T10:00:00Z",
    "created_at": "2025-11-27T10:00:00Z"
}

Get Notification Detail

Endpoint: GET /notifications/{notification_id}

Description: Get detailed information for a single notification.

Response: 200 OK

{
    "id": "notification_uuid",
    "user_id": "user_uuid",
    "notification_type": "new_feature",
    "title": "New Feature Alert!",
    "body": "We've just launched a new feature!",
    "status": "sent",
    "priority": "high",
    "channels": ["email", "push"],
    "data": {},
    "sent_at": "2025-11-27T10:00:00Z",
    "read_at": null,
    "created_at": "2025-11-27T10:00:00Z",
    "updated_at": "2025-11-27T10:00:00Z",
    "delivery_status": [
        {
            "channel": "email",
            "status": "sent",
            "sent_at": "2025-11-27T10:00:00Z",
            "delivered_at": null,
            "error_message": null,
            "attempts": 1
        }
    ]
}

Get Notifications

Endpoint: GET /notifications/

Description: Get paginated list of a user's notifications.

Query Parameters: - page (integer): Page number - limit (integer): Items per page - status_filter (string): Filter by status - notification_type (string): Filter by type

Response: 200 OK

{
    "items": [
        {
            "id": "notification_uuid",
            "user_id": "user_uuid",
            "notification_type": "new_feature",
            "title": "New Feature Alert!",
            "body": "We've just launched a new feature!",
            "status": "sent",
            "priority": "high",
            "channels": ["email", "push"],
            "data": {},
            "sent_at": "2025-11-27T10:00:00Z",
            "read_at": null,
            "created_at": "2025-11-27T10:00:00Z",
            "updated_at": "2025-11-27T10:00:00Z"
        }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "pages": 1
}

Mark Notification as Read

Endpoint: PATCH /notifications/{notification_id}/read

Description: Mark a single notification as read.

Response: 200 OK

{
    "message": "Notification marked as read",
    "id": "notification_uuid",
    "updated_at": "2025-11-27T10:00:00Z"
}

Mark All as Read

Endpoint: PATCH /notifications/read-all

Description: Mark all notifications as read for a user.

Response: 200 OK

{
    "message": "1 notifications marked as read"
}

Notification System Health

Endpoint: GET /notifications/health

Description: Get comprehensive notification system health status.

Response: 200 OK

{
    "status": "healthy",
    "timestamp": "2025-11-27T10:00:00Z",
    "components": {
        "circuit_breakers": {
            "status": "healthy",
            "details": {}
        },
        "metrics": {
            "status": "healthy",
            "details": {}
        },
        "rabbitmq": {
            "status": "healthy",
            "connected": true
        },
        "database": {
            "status": "healthy",
            "connected": true
        }
    }
}

Circuit Breaker Status

Endpoint: GET /notifications/health/circuits

Description: Get detailed circuit breaker status for all external services.

Response: 200 OK

{
    "circuit_breakers": {}
}

Metrics Summary

Endpoint: GET /notifications/health/metrics

Description: Get notification metrics summary.

Response: 200 OK

{
    "metrics": {}
}

Reset Circuit Breaker

Endpoint: POST /notifications/health/circuits/{service}/reset

Description: Manually reset a circuit breaker (admin action).

Response: 200 OK

{
    "message": "Circuit breaker for smtp has been reset",
    "service": "smtp",
    "status": "reset"
}

Get Notification Preferences

Endpoint: GET /notifications/preferences

Description: Get a user's notification preferences.

Response: 200 OK

{
    "id": "preference_uuid",
    "user_id": "user_uuid",
    "mute_all": false,
    "email_enabled": true,
    "push_enabled": true,
    "sms_enabled": false,
    "in_app_enabled": true,
    "quiet_hours_start": "22:00:00",
    "quiet_hours_end": "08:00:00",
    "notification_types": {},
    "created_at": "2025-11-27T10:00:00Z",
    "updated_at": "2025-11-27T10:00:00Z"
}

Update Notification Preferences

Endpoint: PUT /notifications/preferences

Description: Update notification preferences.

Request Body:

{
    "mute_all": true
}

Response: 200 OK

{
    "message": "Preferences updated successfully",
    "id": "preference_uuid",
    "updated_at": "2025-11-27T10:00:00Z"
}

Get Notification Stats

Endpoint: GET /notifications/stats

Description: Get notification statistics for a user.

Response: 200 OK

{
    "total_notifications": 10,
    "unread_count": 5,
    "read_count": 5,
    "by_type": {
        "new_feature": 5,
        "reminder": 5
    }
}