Notification Service

The Notification Service helps you keep users informed with in-app notifications. Whether you need to notify a single user about their order status or broadcast a system-wide announcement, this service handles the delivery, tracking, and management for you.

What you can do:

Send notifications to individual users or broadcast to everyone
Track read/unread status to show notification badges
Let users dismiss notifications with soft deletes
Filter notifications by user, read status, and type
Set expiration times to auto-cleanup old notifications

Interactive API Reference

For complete API documentation with interactive testing, visit our Swagger UI where you can try all endpoints with your own credentials.

View Interactive API Docs

Create a Notification

Send a notification when something important happens in your application—like a completed order, new message, or account update. You can target a specific user or broadcast to everyone. Notifications support different types (info, success, warning, error) for visual styling and custom data payloads for additional context.

curl -X POST https://notifications.stackfordevs.com/v1/notifications \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "userId": "usr_abc123",
    "title": "Order Shipped",
    "message": "Your order #12345 has been shipped!",
    "type": "success",
    "data": {
      "orderId": "12345",
      "trackingUrl": "https://tracking.example.com/12345"
    }
  }'

Notification Types:

info - General information (default)
success - Successful actions
warning - Important warnings
error - Error messages
custom - Custom styling

Tip: Notifications expire after 30 days by default. Set a custom expiresAt date to override this behavior.

Broadcast Notifications

Send system-wide announcements to all users at once—like scheduled maintenance, new feature releases, or important policy updates. Instead of creating thousands of individual notifications, you create one broadcast notification (by setting userId to null) that automatically appears for every user when they fetch their notifications. This is efficient and ensures consistent messaging.

curl -X POST https://notifications.stackfordevs.com/v1/notifications \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "userId": null,
    "title": "Scheduled Maintenance",
    "message": "We will be performing maintenance on Sunday at 2 AM EST.",
    "type": "warning"
  }'

Note: Setting userId: null creates a broadcast that all users will see. Use sparingly for important announcements.

Get User Notifications

Fetch notifications to display in your app's notification center or inbox. When you query by userId, you automatically get both notifications sent directly to that user and any broadcast notifications for all users. Use filters to show only unread notifications, limit results for pagination, or fetch specific types.

curl -X GET "https://notifications.stackfordevs.com/v1/notifications?userId=usr_abc123&read=false&limit=20" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Query Parameters:

userId - Filter by user ID (includes broadcasts)
read - Filter by read status (true/false)
type - Filter by notification type
limit - Max results (default: 20)
offset - Pagination offset (default: 0)

Example Response:

{
  "notifications": [
    {
      "id": "ntf_xyz789",
      "userId": "usr_abc123",
      "title": "Order Shipped",
      "message": "Your order #12345 has been shipped!",
      "type": "success",
      "read": false,
      "createdAt": "2025-11-30T10:00:00Z",
      "data": {
        "orderId": "12345"
      }
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Mark Notification as Read

When a user views or clicks on a notification, mark it as read to update your notification badge count and change its visual state. This is idempotent, so calling it multiple times won't cause errors—useful when handling click events that might fire more than once.

curl -X PATCH https://notifications.stackfordevs.com/v1/notifications/ntf_xyz789/read \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Response: Returns 200 OK with the updated notification including readAt timestamp.

Mark All Notifications as Read

Provide a "Mark all as read" button in your notification center to let users clear their entire notification inbox at once. This is much more efficient than marking each notification individually, especially for users with many unread notifications. The response tells you how many notifications were updated.

curl -X PATCH "https://notifications.stackfordevs.com/v1/notifications/mark-all-read?userId=usr_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Response:

{
  "updated": 12
}

The updated field shows how many notifications were marked as read.

Delete a Notification

Let users dismiss individual notifications they no longer want to see. This performs a soft delete—the notification is hidden from queries but retained in the database with a deletedAt timestamp for audit purposes. Perfect for implementing a "dismiss" or "X" button on notification cards.

curl -X DELETE https://notifications.stackfordevs.com/v1/notifications/ntf_xyz789 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Response: Returns 204 No Content on success. Deleted notifications won't appear in future queries.

Get Single Notification

Retrieve a specific notification by its ID. Useful for deep linking to specific notifications or refreshing notification details.

curl -X GET https://notifications.stackfordevs.com/v1/notifications/ntf_xyz789 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Error Codes

The Notification API uses standard HTTP status codes.

Status	Description
200	Success - Request completed successfully
201	Created - Notification created successfully
204	No Content - Notification deleted successfully
400	Bad Request - Missing required fields or invalid parameters
401	Unauthorized - Missing or invalid API keys
404	Not Found - Notification doesn't exist or was deleted