canonical: https://jentic.com/apis/novu.co/novu # Novu API Jentic publishes the only available OpenAPI specification for Novu API, keeping it validated and agent-ready. Orchestrate multi-channel notifications across email, SMS, push, in-app, and chat from a unified API with 102 endpoints. Define notification workflows with step-based logic, manage subscriber preferences, and route messages through configurable provider integrations. Supports topic-based fan-out, bulk subscriber operations, and per-subscriber channel credential management. ## For AI agents Trigger multi-channel notifications (email, SMS, push, in-app, chat), manage subscriber preferences, and orchestrate notification workflows from a single API. ## Scope Does not handle direct email composition, SMS routing, or push certificate management - use for notification orchestration and delivery coordination only. ## Capabilities - Trigger notifications across email, SMS, push, in-app, and chat channels with a single event call - Define multi-step notification workflows with conditional routing and delay logic - Fan out notifications to subscriber groups via topic-based pub/sub - Track per-subscriber notification preferences and channel opt-in status - Route messages through multiple provider integrations with automatic failover - Broadcast announcements to all subscribers without individual addressing - Manage notification templates and layouts with preview and localization support ## Use cases ### AI Agent Notification Orchestration AI agents trigger multi-channel notifications through Jentic by searching for the event trigger operation, loading the schema, and executing with the event name, subscriber ID, and payload. Jentic handles ApiKey injection from your Jentic One instance. A single POST to `/v1/events/trigger` delivers the notification across all channels defined in the workflow - email, SMS, push, in-app, and chat - without the agent managing individual provider integrations. Example prompt: Trigger a notification event named 'order-shipped' for subscriber 'user-123' with payload containing order_id and tracking_url via POST `/v1/events/trigger` ### Subscriber Preference Management Allow end users to control which notification channels they receive messages on. The API exposes per-subscriber, per-workflow preference endpoints that respect opt-out choices at delivery time. Agents can read and update preferences programmatically, enabling self-service notification settings without building custom preference UIs from scratch. Example prompt: Retrieve notification preferences for subscriber 'user-456' via GET `/v2/subscribers/{subscriberId}/preferences` and disable the email channel for the 'marketing-updates' workflow ### Topic-Based Fan-Out Group subscribers into topics and send a single trigger to notify all members simultaneously. Topics support dynamic membership - subscribers can be added or removed at any time. This pattern handles use cases like product update announcements, team notifications, and event alerts without maintaining recipient lists in application code. Example prompt: Create a topic named 'product-updates' via POST `/v2/topics`, add 3 subscribers to it, then trigger a broadcast notification to the topic ### In-App Notification Feed Power an in-app notification center by fetching a subscriber's notification feed with read/unread status. The API supports marking individual messages or all messages as read, tracking unseen counts for badge displays, and filtering by notification category. This eliminates the need to build notification storage and retrieval infrastructure. Example prompt: Fetch the notification feed for subscriber 'user-789' via GET `/v1/subscribers/{subscriberId}/notifications/feed` and mark all as read via POST `/v1/subscribers/{subscriberId}/messages/mark-all` ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/events/trigger` | Trigger a notification event for one or more subscribers | | POST | `/v1/events/trigger/broadcast` | Broadcast a notification to all subscribers | | POST | `/v1/events/trigger/bulk` | Trigger multiple notification events in a single request | | GET | `/v2/subscribers/{subscriberId}/preferences` | Get subscriber notification preferences | | POST | `/v2/topics` | Create a notification topic for fan-out | | GET | `/v1/subscribers/{subscriberId}/notifications/feed` | Get a subscriber's notification feed | | POST | `/v2/workflows` | Create a notification workflow | | GET | `/v1/integrations/active` | List active notification provider integrations | ## Key resources - **Events** — Trigger notifications, broadcast to all subscribers, and bulk-trigger events - **Subscribers** — Manage subscriber profiles, credentials, preferences, and notification feeds - **Topics** — Create topics and manage subscriber membership for fan-out notifications - **Workflows** — Define multi-step notification workflows with channel routing and delays - **Integrations** — Configure and manage notification provider connections (email, SMS, push) - **Messages** — List sent notifications and manage message lifecycle ## Why Jentic - **Setup:** Wiring Novu by hand means setting up its ApiKey Authorization header, choosing the right US or EU host (api.novu.co or eu.api.novu.co), and threading that through trigger, subscriber, and workflow calls yourself across more than a hundred endpoints. Through Jentic you install once, import the Novu API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Novu triggers events from the request body rather than a resource id in the URL path, so scope the agent to the operations it needs, such as triggering an event and reading a subscriber feed. You choose that set, so creating workflows or topics is not included unless you add it. - **Credential handling:** Your Novu API key is stored once, encrypted, by your own Jentic One instance and injected at execution time as the Authorization header. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'trigger a multi-channel notification' or 'read a subscriber feed', and Jentic returns the matching Novu operation with its input schema so the agent calls `/v1/events/trigger` without browsing the reference docs. ## Related APIs - **OneSignal API** — OneSignal focuses on push notifications and in-app messaging with rich targeting and analytics - **Twilio SendGrid Mail API** — SendGrid provides dedicated high-volume email delivery that Novu can route through as a provider - **Twilio REST API** — Twilio provides SMS and voice capabilities that Novu can leverage as delivery providers - **Pusher API** — Pusher provides real-time WebSocket channels for live in-app messaging alongside Novu's notification infrastructure ## FAQ ### Why is there no official OpenAPI spec for Novu API? Novu does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Novu API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Novu API use? The Novu API uses API key authentication via the Authorization header with format 'ApiKey '. Through Jentic, your Novu API key is stored encrypted in your Jentic One instance and injected automatically, so agents never handle the raw secret key. ### Can I send notifications to multiple channels with a single API call? Yes. POST to `/v1/events/trigger` with your event name and subscriber ID. The notification routes through all channels defined in the associated workflow - email, SMS, push, in-app, and chat - based on the subscriber's active integrations and preferences. ### What are the rate limits for the Novu API? Novu enforces rate limits based on your plan tier. The trigger endpoint supports up to 300 events per second on the Business plan. Bulk trigger via POST `/v1/events/trigger/bulk` accepts up to 100 events per request for higher throughput. The API returns 429 with retry guidance when limits are hit. ### How do I trigger a notification through Jentic with the Novu API? Search for 'trigger a multi-channel notification' in Jentic to find the Novu events trigger endpoint. Load the operation schema, then execute with the event name, subscriberId, and payload object. Install with pip install jentic and use the search-load-execute flow. Jentic injects the ApiKey header automatically. ### Does the Novu API support subscriber notification preferences? Yes. GET `/v2/subscribers/{subscriberId}/preferences` returns per-workflow channel preferences. PATCH the same endpoint to update preferences. Novu respects these preferences at delivery time - if a subscriber opts out of email for a specific workflow, the notification skips the email step automatically. ### Can I use topics for group notifications in Novu? Yes. Create a topic via POST `/v2/topics` with a topicKey, then add subscribers via POST `/v2/topics/{topicKey}/subscriptions.` Trigger a notification to the topic and all subscribed members receive it. Topics support dynamic membership - add or remove subscribers at any time without modifying the trigger logic. ### Can I limit what my agent is allowed to do with the Novu API? Yes. Because you self-host Jentic One, your own rules decide which Novu operations and credentials the agent may use. Since Novu triggers events from the request body rather than a resource id in the URL path, you scope the agent to just the operations it needs, such as triggering an event with POST `/v1/events/trigger` and reading a subscriber feed with GET `/v1/subscribers/{subscriberId}/notifications/feed.` Anything you leave out, like creating workflows via POST `/v2/workflows` or topics via POST `/v2/topics`, stays off limits unless you add it.