Skip to main content

In-app notifications API

Three endpoints and no queue to run. Send a notification to a user id from your server or an agent, read unread ones from the browser, mark them read.

Get an API key → Polling notifications from the client

What exists today

  • Notifications are addressed to a user id you choose; there is no user directory to sync.
  • Clients poll the unread endpoint with a publishable key, so no server round-trip is needed to render a bell icon.
  • Read state is per notification. Old notifications are pruned automatically after 90 days.
  • Sending accepts an Idempotency-Key header, so retries never duplicate a message.
  • The notifications API is part of the Builder plan.

Endpoints

POST /v1/notifications Send to a user id
GET /v1/notifications/unread Unread for a user (publishable key allowed)
PATCH /v1/notifications/{id}/read Mark as read

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
  • get_unread_notifications
  • mark_notifications_read

Arguments, example prompts and client setup →

Questions

Is this push or polling?
Polling. The unread endpoint is cheap and cacheable, and it works 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.