Notifications API

The Notifications API allows you to programmatically manage and deliver notifications to users within your application. This API provides endpoints for creating, retrieving, updating, and deleting notifications, as well as for listing existing notifications.

Endpoints

All API requests should be made to the base URL: https://api.msdn.example.com/v1/notifications

Create Notification

This endpoint allows you to send a new notification to one or more recipients.

POST /v1/notifications

Request Body Parameters

Parameter Type Required Description
title String Yes The title of the notification.
message String Yes The main content of the notification. Supports basic Markdown formatting.
recipientIds Array of Strings Yes A list of user IDs to send the notification to.
priority String No The priority level of the notification (e.g., high, normal, low). Defaults to normal.
imageUrl String No An optional URL for an image to be displayed with the notification.
actionUrl String No An optional URL to navigate to when the notification is clicked.

Example Request

{
    "title": "New Feature Announcement",
    "message": "Check out our latest update! It includes [new feature description] and bug fixes.",
    "recipientIds": ["user_123", "user_456"],
    "priority": "high",
    "imageUrl": "https://example.com/images/new_feature.png",
    "actionUrl": "https://msdn.example.com/features/latest"
}

Get Notification

Retrieve details of a specific notification by its ID.

GET /v1/notifications/{notificationId}

Path Parameters

Parameter Type Required Description
notificationId String Yes The unique identifier of the notification to retrieve.

Example Request

GET /v1/notifications/notif_abc123

List Notifications

Retrieve a list of notifications for the authenticated user. Supports filtering and pagination.

GET /v1/notifications

Query Parameters

Parameter Type Required Description
userId String No Filter notifications by a specific user ID.
status String No Filter by notification status (e.g., unread, read).
limit Integer No Maximum number of notifications to return. Defaults to 20.
offset Integer No Number of notifications to skip for pagination. Defaults to 0.

Example Request

GET /v1/notifications?userId=user_123&status=unread&limit=10

Update Notification

Update the status of a notification.

PATCH /v1/notifications/{notificationId}

Path Parameters

Parameter Type Required Description
notificationId String Yes The unique identifier of the notification to update.

Request Body Parameters

Parameter Type Required Description
status String Yes The new status for the notification (e.g., read, archived).

Example Request

PATCH /v1/notifications/notif_abc123
{
    "status": "read"
}

Delete Notification

Delete a notification by its ID.

DELETE /v1/notifications/{notificationId}

Path Parameters

Parameter Type Required Description
notificationId String Yes The unique identifier of the notification to delete.

Example Request

DELETE /v1/notifications/notif_abc123

Common Response Codes

Code Description
200 OK Request successful.
201 Created Notification successfully created.
204 No Content Notification successfully deleted or updated with no content in response.
400 Bad Request Invalid request payload or parameters.
401 Unauthorized Authentication credentials are missing or invalid.
404 Not Found The requested notification or resource does not exist.
500 Internal Server Error An unexpected error occurred on the server.

Full Examples

Sending a Targeted Notification

Send a high-priority notification with an image and a call to action.

POST /v1/notifications
Host: api.msdn.example.com
Authorization: Bearer YOUR_API_KEY

{
    "title": "Urgent Security Alert",
    "message": "Your account has detected unusual activity. Please review your recent logins.",
    "recipientIds": ["user_789"],
    "priority": "high",
    "imageUrl": "https://example.com/images/alert.png",
    "actionUrl": "https://msdn.example.com/account/security"
}

Expected Response (201 Created):

{
    "id": "notif_xyz789",
    "title": "Urgent Security Alert",
    "message": "Your account has detected unusual activity. Please review your recent logins.",
    "recipientIds": ["user_789"],
    "status": "sent",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z",
    "priority": "high",
    "imageUrl": "https://example.com/images/alert.png",
    "actionUrl": "https://msdn.example.com/account/security"
}

Marking a Notification as Read

Update the status of a notification to indicate it has been read.

PATCH /v1/notifications/notif_abc123
Host: api.msdn.example.com
Authorization: Bearer YOUR_API_KEY

{
    "status": "read"
}

Expected Response (204 No Content)