Skip to main content
20% off 3 months · code LAUNCH20 · until 31 October

In-app notifications API

No queue to run. Send a notification to one user id or to everyone from your server or an agent, and show it in a bell that one script tag adds to your app, or read it through the API and draw your own.

Get an API key → Notifications: send, broadcast, changelog to the bell

What exists today

  • Every plan includes notifications, counted per project per calendar month. A broadcast to everyone counts once, however many people read it.
  • Notifications are addressed to a user id you choose; there is no user directory to sync. A broadcast (audience "all") reaches every user id that asks within 30 days of it being sent.
  • A browser proves which user it is: your server computes user_hash = HMAC-SHA256(signing secret, user_id) and the page sends it with the publishable key. Without a matching hash the API refuses, so nobody can read another user's notifications.
  • A changelog entry can post itself to the bell when it publishes (notify_in_app): one broadcast with the title, a short excerpt and a link to the entry, never twice.
  • Read state is per user: a direct notification is read once, a broadcast is read separately by each person. Notifications and their read state are deleted after 90 days.
  • Sending accepts an Idempotency-Key header, so retries never duplicate a message.
  • The bell widget is one script tag (cdn.nordva.dev/v1/notifications.js): a bell with the unread count, a panel with All and Unread, mark read and mark all read, a sheet on phones, light or dark, in your header or floating. It works under a strict Content-Security-Policy.

Endpoints

POST /v1/notifications Send to a user id, or to everyone
GET /v1/notifications/inbox A user's recent notifications and unread count (publishable key with user_hash)
GET /v1/notifications/unread/count The number on the bell (publishable key with user_hash)
PATCH /v1/notifications/{id}/read Mark one read for a user
PATCH /v1/notifications/read-all Mark everything read for a user
GET /v1/notifications What was sent, with how many people read it

Full reference with request and response schemas: docs.nordva.dev. Every response uses the same envelope and stable error codes.

MCP tools

The same operations are available to Claude Code, Claude Desktop and Cursor through the Nordva MCP server at mcp.nordva.dev:

  • send_notification
  • list_notifications
  • get_notification
  • delete_notification
  • get_unread_notifications
  • mark_notifications_read
  • get_notification_settings
  • update_notification_settings
  • create_notifications_signing_secret
  • rotate_notifications_signing_secret

Arguments, example prompts and client setup →

Questions

Is this push or polling?
Polling. The endpoints are cheap and work from any client without a socket. Streaming is not offered today.
Does it send email or SMS?
No. This primitive is in-app only. Email exists in the changelog and waitlist primitives where it belongs.
Can a visitor read someone else's notifications?
Not when the page sends a user_hash. It is an HMAC of the user id made on your server with a secret that never reaches the browser, and the API checks it on every browser call.