Wiki · Concept · Last reviewed June 25, 2026

Notifications API

The Notifications API is the web-platform interface for displaying system-level notifications to users outside the visible page.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, notifications, service workers, attention, agents, permission prompts

Definition

The Notifications API is the WHATWG standard for displaying notifications to the end user, usually outside the top-level browsing context's viewport. The standard is designed to work across different operating-system notification systems while staying platform-independent. As reviewed on June 25, 2026, the WHATWG page identified the Notifications API as a Living Standard last updated March 15, 2026.

MDN describes the API as letting web pages control system notifications. Those notifications are rendered by the operating system's native notification system, so they can appear even when the user has moved away from the page. That makes the API an attention surface, not merely a visual widget.

How It Works

Notifications require permission from the current origin. MDN says this is generally requested through Notification.requestPermission() and should be called in response to a user gesture. The API exposes both non-persistent and persistent notifications. Non-persistent notifications are created from a page or browsing context with the Notification() constructor, and their lifetime is tied to that page.

Persistent notifications are created through ServiceWorkerRegistration.showNotification(). The WHATWG standard defines showNotification(title, options) and getNotifications() on ServiceWorkerRegistration, and defines notificationclick and notificationclose event handlers on ServiceWorkerGlobalScope. MDN marks showNotification() as widely available, but marks the broader Notifications API and notificationclick event as limited availability, so compatibility claims need browser and platform context.

Agent Context

For AI Browsers and Computer Use, notifications are a route from background software into human attention. A browser agent, support tool, tutoring system, workplace dashboard, mailbox, calendar, or shopping assistant can use a notification to interrupt the user, report completion, request approval, or bring the user back into a workflow.

This is different from the Push API. Push concerns delivery of a message from an application server to the user agent. Notifications concern the displayed artifact, its permission state, title, body, icon, tag, action buttons, click handling, and whether an interaction opens or focuses a client. An agent review should keep those layers separate.

Governance Use

Governance should treat notifications as user-facing acts. A notification can steer attention, create urgency, impersonate institutional priority, or invite one-click action. The record should say whether the notification was caused by a human request, a scheduled rule, a service-worker event, a server push, or an autonomous agent decision.

For high-impact workflows, notification actions should not bypass ordinary confirmation. A button labeled "approve," "archive," "send," "confirm," or "dismiss case" can be more than a reminder. It can become a decision surface. Agent systems should separate notification display from irreversible action, and should preserve user-visible text, action identifiers, and click outcomes.

Limits

The Notifications API is not a consent system, authentication method, task queue, delivery guarantee, or complete audit trail. Permission to display notifications does not prove permission to message constantly, escalate urgency, or act on the user's behalf. Operating systems and browsers may modify notification presentation, suppress notifications, or apply their own rules.

Notification content also has privacy risk. Titles and bodies can reveal account activity, health information, workplace status, financial events, or relationship context on a lock screen or shared device. A governed deployment should assume that a notification may be seen by someone other than the intended user.

Minimum Evidence Record

For agent-mediated notifications, record the origin, top-level site where relevant, permission state, triggering event, service worker registration scope, title class, body class, tag, action identifiers, silent or require-interaction flags, timestamp, delivery attempt, click or close event, resulting URL or workflow, and agent task identifier. Avoid storing sensitive notification text unless the audit purpose requires it and retention is justified.

Source Discipline

Use the WHATWG Notifications API Standard for interface definitions, persistent versus non-persistent notification mechanics, service-worker events, actions, tags, and options. Use MDN for implementation-oriented summaries, permission guidance, secure-context notes, Baseline or limited-availability status, and browser-facing examples. Do not collapse Notifications API with Push API: a push message can exist without a displayed notification, and a notification can be displayed without a network push.

Spiralist Reading

Spiralism reads notifications as claims on attention. The page has fallen silent, but the origin can still knock. That power can be humane when it reminds, warns, or completes a promised task. It becomes extractive when it turns every background event into a summons.

Sources

Return to Wiki