Skip to main content

Topics

A topic is a named group of subscribers you can send to as one. Use it when the recipient list is a property of the content — everyone following a coach, everyone in a challenge — rather than something you can compute per send.

The alternative is manage/broadcast, which reaches every subscriber in the tenant and takes no list at all.

Every endpoint here is a management endpoint: secret key (sk_*) or admin JWT.

Create a Topic​

POST /api/v1/notifications/manage/create-topic
{
  "topicKey": "weekly-updates",
  "name": "Weekly Updates"
}

Response:

{
  "topicKey": "weekly-updates",
  "topicId": "6512f0a1c3d4e5f60718293c"
}

topicKey is the identifier you choose and use everywhere else; topicId is the provider's internal ID and is rarely needed.

Add and Remove Subscribers​

Up to 100 users per call.

POST /api/v1/notifications/manage/add-subscribers-to-topic
{
  "topicKey": "weekly-updates",
  "userIds": ["user-1", "user-2"]
}

Response:

{
  "totalCount": 2,
  "successful": 2,
  "failed": 0
}

Partial failure is normal and does not fail the request — check failed, and read errors for the per-user reason:

{
  "totalCount": 2,
  "successful": 1,
  "failed": 1,
  "errors": [
    {
      "subscriberId": "user-2",
      "code": "not_found",
      "message": "subscriber does not exist"
    }
  ]
}
POST /api/v1/notifications/manage/remove-subscribers-from-topic
{
  "topicKey": "weekly-updates",
  "userIds": ["user-1"]
}

Response: the same totalCount / successful / failed / errors shape.

Send to a Topic​

POST /api/v1/notifications/manage/send-to-topic
{
  "workflowId": "push-notification",
  "topicKey": "weekly-updates",
  "payload": {
    "title": "Weekly Update",
    "body": "Your weekly health summary is ready"
  },
  "excludeUserId": "user-admin"
}

Response:

{
  "acknowledged": true,
  "status": "processed",
  "transactionId": "txn_def456"
}

excludeUserId skips a single recipient — normally whoever triggered the event, so they are not notified about their own action.

List Subscribers​

POST /api/v1/notifications/manage/list-topic-subscribers
{
  "topicKey": "weekly-updates",
  "page": 1,
  "pageSize": 50
}

Response:

{
  "userIds": ["user-1", "user-2"],
  "totalCount": 2,
  "hasMore": false
}

Check One Subscription​

Cheaper than paging the whole list when you only need to render a follow/unfollow button.

POST /api/v1/notifications/manage/check-topic-subscription
{
  "topicKey": "weekly-updates",
  "userId": "user-1"
}

Response:

{
  "isSubscribed": true
}

isSubscribed is omitted when false, so read it with a default rather than checking for its presence.

Delete a Topic​

Removes the topic and every subscriber association with it. Subscribers themselves are untouched, and notifications already in flight are not cancelled.

POST /api/v1/notifications/manage/delete-topic
{
  "topicKey": "weekly-updates"
}

Response:

{
  "acknowledged": true,
  "status": "done"
}

status is Novu's own acknowledgement string when it sends one, and defaults to "done" otherwise — so compare on acknowledged, not on the text.