Manage Topics

Novu provides multiple ways to manage topics, either through the dashboard or the API. Both options give you flexibility depending on whether you prefer a UI-based workflow or direct API integration.

Create a Topic

Creating a topic defines a new group of subscribers that can later be targeted in workflow triggers. You can create a topic either from the Dashboard or using the API:

Create a topic via dashboard

1. Login to the Novu dashboard
2. Go to Topics in the left navigation.
3. Click the Create Topic button.
4. Provide a unique Name and Topic Key.
5. Click on the Create topic button.

Create a topic via API

You can create a new topic using the topics.create method.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
 
async function run() {
  const result = await novu.topics.create({
    key: "task:12345",
    name: "Task Title",
  });
 
  console.log(result);
}
 
run();

Novu also supports on-the-fly topic creation. If you attempt to add subscribers to a topic key that doesn't exist for the selected environment and organization, Novu will automatically create a new topic named Autogenerated-<TOPIC_KEY> and assign the subscribers to it.

This auto-generated topic can then be renamed and managed just like any other topic created manually.

Retrieve a topic

Retrieving a topic allows you to confirm that it exists and view its details, including the name and key.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
 
async function run() {
  const result = await novu.topics.get("<value>");
 
  console.log(result);
}
 
run();

Update a topic name

You can update the display name of a topic to better reflect its purpose. The topicKey itself is permanent and cannot be modified after the topic is created.

Update a topic name via dashboard

1. Log in to the Novu dashboard
2. From the Topics page, click on the topic you want to update
3. From the Overview tab, update the name of the topic
4. Click Save changes to save.

Update a topic name via API

Use the topics.update method with the topic's key to update the name of a topic

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
 
async function run() {
  const result = await novu.topics.update(
    { name: "Updated Topic Name" },
    "task:12345" // topicKey
  );
 
  console.log(result);
}
 
run();

List all topics

Listing topics lets you see all groups that have been created in the current environment. This is useful for confirming available topic keys and checking which topics exist before triggering workflows.

Get list of topics via dashboard

1. Log in to the Novu dashboard
2. From the Topics page, you will see the list of all topics that have bee created either from the dashboard or using the API.

List all topics via API

Use the topics.list method.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
 
async function run() {
  const result = await novu.topics.list({});
  console.log(result);
}
 
run();

Delete a topic

Deleting a topic permanently removes the grouping, but it does not affect the subscribers themselves. This action is irreversible, so be sure you no longer need the topic before deleting it.

Delete a topic via dashboard

1. Log in to the Novu dashboard
2. From the Topics page, click on the topic you want to delete.
3. Click Delete topic.
4. A modal will appear; click Delete topic again to confirm.

Delete a topic via API

Use the topics.delete method with the topic's key.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
 
async function run() {
  const result = await novu.topics.delete("task:12345"); // topicKey
 
  console.log(result);
}
 
run();

Manage topic subscriptions

A topic subscription is a relationship between a subscriber and a topic. Subscriptions track which subscribers belong to which topics.

Subscribers can be added to or removed from a topic at any time, either from the Novu dashboard or through the API.

Add subscribers to a topic

Adding subscribers to a topic ensures that they receive all notifications sent to that topic. You can add individual subscribers or multiple subscribers at once, depending on your needs.

Add subscribers to a topic via dashboard

1. Log in to the Novu dashboard.
2. From the Topics page, select the topic you want to manage.
3. Go to the Subscriptions tab.
4. Search for and select the subscribers you want to add either using Email, Name, Phone or SubscriberId.
5. Select the subscriber to add them to the topic.

Add subscribers to a topic via API

Use the topics.subscriptions.create() method to add one or more subscribers to a topic, referencing the topic's key and an array of subscriberIds.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
 
async function run() {
  const result = await novu.topics.subscriptions.create("task:12345", {
    subscriberIds: [
      "subscriberId1",
      "subscriberId2",
    ],
  });
 
  console.log(result);
}
 
run();

Remove subscribers from a topic

Removing subscribers from a topic stops them from receiving notifications sent to that topic. The subscribers remain active in Novu but will no longer be part of that specific group.

Remove subscribers from a topic via dashboard

1. Log in to the Novu dashboard.
2. From the Topics page, select the topic.
3. Go to the Subscriptions tab.
4. Locate the subscriber(s) you want to remove.
5. Click on the delete icon next to the user who you want to remove from the topic.
6. In the menu that appears, click Remove.

Remove subscribers from a topic via API

You can use the API to remove one or more subscribers from the topic which a single API call by providing their subscriberIds.

import { Novu } from "@novu/api";
 
const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});
 
async function run() {
  const result = await novu.topics.subscriptions.delete({
    subscriberIds: [
      "subscriberId1",
      "subscriberId2",
    ],
  }, "<value>");
 
  console.log(result);
}
 
run();

List subscribers in a topic

You can view all subscribers currently assigned to a specific topic.

List subscribers in a topic via dashboard

1. Log in to the Novu dashboard.
2. From the Topics page, select the topic.
3. Go to the Subscriptions tab to see the list of subscribers currently assigned.

List subscribers in a topic via API

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
 
async function run() {
  const result = await novu.topics.subscriptions.list({
    topicKey: "task:12345",
  });
 
  console.log(result);
}
 
run();

Check subscriber subscription

You can confirm whether a specific subscriber belongs to a given topic. This is useful when validating membership before triggering workflows or debugging unexpected notification behavior.

Check subscriber subscription via dashboard

1. Log in to the Novu dashboard.
2. From the Topics page, select the topic.
3. Go to the Subscriptions tab.
4. Use the search bar to look up the subscriber. If they are subscribed, they will appear in the list.

Check subscriber subscription via API

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
 
async function run() {
  const result = await novu.topics.subscribers.retrieve(
    "task:12345", // topicKey
    "subscriber-id-to-check" // subscriberId
  );
 
  console.log(result);
}
 
run();

Explore the topics APIs

These are commonly used topics APIs. Explore all topics APIs on topics API Reference documentation.