Skip to main content
POST
cURL
Add one entry to your project’s preference catalog. Strict — creating an entry whose (channel, topic, event, medium) already exists returns 409. To change an existing entry use update; to declaratively set a whole catalog use bulk upsert.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer bv_xxxxxxxxx, where bv_xxxxxxxxx is your API Key with Full access scope.

Body

application/json
channel
string
required

Broad category (e.g. "digest").

topic
string
required

Subcategory. any matches all topics under the channel/event; none is the base channel/event.

event
string
required

Event that triggers the notification (e.g. "sent").

name
string
required

Human-readable name for the catalog entry (e.g. "Weekly digest").

default_enabled
boolean
required

The project-level default for recipients who have set no preference of their own.

medium
enum<string>
default:in_app

The medium this catalog entry gates. Defaults to in_app.

Available options:
in_app,
email
description
string

Optional longer blurb shown alongside the name on a settings screen. Omitted or blank stores none.

mandatory
boolean
default:false

Whether recipients may opt out. A mandatory entry is cataloged (so sends pass the target gate) but its recipient toggle is refused with a 400, and any rule a recipient already had is ignored. For transactional notifications — password resets, security alerts, a one-shot welcome. default_enabled still applies, so setting it false stops the notification: mandatory removes the recipient's choice, not yours. Defaults to false.

Response

Catalog entry created.