Notifications

Web notifications are short, actionable messages delivered in-app. Each notification carries a structured content payload (subject, body, optional CTA) and a lifecycle — created, read, dismissed, or expired.

Notification State

A notification is considered current when it is neither dismissed nor expired. read_at and dismissed_at are timestamps; setting either to a value transitions the notification's state. Expiry is server-side and not settable via the API.

GET /api/resource/web_notifications
List notifications. With no filter, returns all current (not dismissed, not expired) notifications. Pass filter=read or filter=unread to scope the result.

Parameters

Name Type Required Description
filter string Optional Either "read" or "unread". Omit for the full current set.

Response

200 OK
Returns an array of notification objects with structured content.
[
  {
    "id": 123,
    "content": {
      "subject": "Daily Goal Achieved!",
      "body": "You hit your 4-hour focus goal.",
      "cta_url": "https://www.rescuetime.com/dashboard",
      "cta_text": "View dashboard",
      "tags": [
        "goal",
        "achievement"
      ]
    },
    "read_at": null,
    "dismissed_at": null,
    "created_at": "2026-04-15T18:00:00Z"
  }
]

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.rescuetime.com/api/resource/web_notifications?filter=unread"
GET /api/resource/web_notifications/read
Convenience: list only notifications that have been read (regardless of dismissed/expired state).

Response

200 OK
Returns an array of read notifications.
GET /api/resource/web_notifications/counts
Return current read/unread counts. Useful for rendering badges without pulling the full list.

Response

200 OK
Returns { read: <count>, unread: <count> } over the not-dismissed, not-expired set.
{
  "read": 12,
  "unread": 3
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.rescuetime.com/api/resource/web_notifications/counts
GET /api/resource/web_notifications/:id
Retrieve a single notification.

Parameters

Name Type Required Description
id integer Required Notification ID.

Response

200 OK
Returns the notification object.
POST /api/resource/web_notifications
Create a notification. Primarily intended for tooling and internal flows; most user-facing notifications are produced by the system.

Parameters

Note: This endpoint expects a JSON request body. Set the Content-Type: application/json header and format parameters as a JSON object.

Name Type Required Description
web_notification.content.subject string Required Headline shown in the notification list.
web_notification.content.body string Optional Longer text shown when the notification is opened.
web_notification.content.cta_url string Optional Destination URL for the call-to-action.
web_notification.content.cta_text string Optional Button label for the call-to-action.
web_notification.content.tags array<string> Optional Free-form tags for filtering and grouping.

Response

200 OK
Returns the newly created notification.

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"web_notification":{"content":{"subject":"Heads up","body":"Your week-in-review is ready.","cta_url":"https://www.rescuetime.com/dashboard","cta_text":"Open"}}}' \
  https://www.rescuetime.com/api/resource/web_notifications
PATCH /api/resource/web_notifications/:id
Update a notification. Typical use: set read_at to mark as read, or dismissed_at to dismiss. content fields can also be edited.

Parameters

Note: This endpoint expects a JSON request body. Set the Content-Type: application/json header and format parameters as a JSON object.

Name Type Required Description
id integer Required Notification ID.
web_notification.read_at datetime Optional Timestamp the user read the notification. Set to null to mark unread.
web_notification.dismissed_at datetime Optional Timestamp the user dismissed the notification.
web_notification.content object Optional Same shape as create (subject, body, cta_url, cta_text, tags).

Response

200 OK
Returns the updated notification.

Example Request

curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"web_notification":{"read_at":"2026-04-15T12:00:00Z"}}' \
  https://www.rescuetime.com/api/resource/web_notifications/123
DELETE /api/resource/web_notifications/:id
Permanently delete a notification. Use dismissed_at instead if you want it preserved for history.

Parameters

Name Type Required Description
id integer Required Notification ID.

Response

200 OK
Returns the deleted notification.

Where Notifications Come From

The system creates notifications for goal achievements, alert thresholds, weekly summaries, and product announcements. Tags on the content payload let client UIs group or filter messages by topic.

Related Resources

Cookies help us deliver our services. By using our services, you agree to our use of cookies.