List notifications
Retrieve the authenticated user’s recent notifications, ordered by most recent first.
Authentication: Required
Rate limit: Standard
Query parameters:
| Parameter | Type | Default | Description |
|---|
limit | integer | 50 | Number of notifications to return. Min: 1, max: 100. |
unread_only | string | "false" | Set to "true" to return only unread notifications. |
200 OK:
{
"notifications": [
{
"id": "ntf_12345",
"user_id": "usr_abc",
"type": "security_alert",
"title": "New device sign-in",
"body": "A new device signed in to your account from San Francisco, CA.",
"color": "red",
"icon": "shield-alert",
"action_url": "/dashboard/security",
"actor_id": null,
"actor_email": null,
"actor_name": null,
"metadata": { "device": "Chrome on macOS", "ip": "203.0.113.42" },
"is_read": false,
"created_at": "2026-03-05T14:30:00Z"
},
{
"id": "ntf_67890",
"user_id": "usr_abc",
"type": "share_request",
"title": "Password shared with you",
"body": "Alice shared GitHub credentials with you.",
"color": "default",
"icon": null,
"action_url": "/dashboard/passwords",
"actor_id": "usr_def",
"actor_email": "alice@example.com",
"actor_name": "Alice",
"metadata": {},
"is_read": true,
"created_at": "2026-03-04T09:15:00Z"
}
],
"unread_count": 3
}
| Field | Type | Description |
|---|
notifications | array | Array of notification objects, ordered by created_at descending |
unread_count | integer | Total number of unread notifications for the user (independent of the limit parameter) |
The unread_count is computed in parallel with the notification list query for efficiency. It always reflects the total unread count, not just the count within the returned page.
Create notification
Create a notification for the authenticated user. Typically called server-side by internal systems (security alerts, sharing events, system updates).
Authentication: Required
Rate limit: 30 requests per 60 seconds per user
Request body:
{
"user_id": "usr_abc",
"type": "security_alert",
"title": "New device sign-in",
"body": "A new device signed in to your account.",
"color": "red",
"icon": "shield-alert",
"action_url": "/dashboard/security",
"actor_id": "usr_def",
"actor_email": "alice@example.com",
"actor_name": "Alice",
"metadata": { "device": "Chrome on macOS" }
}
| Field | Type | Required | Description |
|---|
user_id | string (UUID) | Yes | Target user ID. Must match the authenticated user. |
type | string | Yes | Notification type (e.g., security_alert, share_request, info). Max 100 characters. |
title | string | Yes | Short title. Max 500 characters. |
body | string | Yes | Full notification message. Max 5000 characters. |
color | string | No | Color theme for the notification badge. Default: "default". Max 50 characters. |
icon | string | No | Icon identifier. Max 200 characters. |
action_url | string (URL) | No | URL to navigate to when the notification is clicked. Max 2000 characters. |
actor_id | string (UUID) | No | User ID of the actor who triggered the notification. |
actor_email | string (email) | No | Email of the actor. |
actor_name | string | No | Display name of the actor. Max 200 characters. |
metadata | object | No | Arbitrary JSON metadata. Default: {}. |
Users can only create notifications for themselves. If user_id does not match the authenticated user’s ID, the endpoint returns 403 Forbidden.
201 Created:
{
"notification": {
"id": "ntf_new",
"user_id": "usr_abc",
"type": "security_alert",
"title": "New device sign-in",
"body": "A new device signed in to your account.",
"is_read": false,
"created_at": "2026-03-05T14:30:00Z"
}
}
| Status | Code | Description |
|---|
400 | validation_failed | Missing or invalid required fields |
403 | forbidden | user_id does not match the authenticated user |
429 | rate_limited | Rate limit exceeded |
500 | internal_error | Database insert failed (sanitized message) |
Clear all notifications
Delete all notifications for the authenticated user.
DELETE /api/notifications
200 OK:
Errors:
| Status | Code | Description |
|---|
429 | rate_limited | Rate limit exceeded |
500 | internal_error | Database delete failed (sanitized message) |
This endpoint deletes all notifications for the user, including both read and unread. There is no undo. Individual notification deletion is not currently supported via this endpoint.
