Skip to main content
Use the Catalog REST API to manage reference data such as products or content together with its schema. In a message, look up stored values with the Liquid tags catalog_items and catalog_selection_items.
Store only reference data that does not identify people. Include data_classification: "non_personal" when you create a catalog. Keep user IDs, email addresses, phone numbers, device tokens, and other identifying values out of catalog fields and items.

Supported resources and operations

The base URL is https://api.notifly.tech. Catalog routes belong to a project.
The public API reads and changes catalogs that meet all three conditions.
  • The data source is api.
  • The data classification is non_personal.
  • The catalog status is active.
Google Sheets catalogs do not appear in the public REST API list. Manage their sources and synchronization in the console. For catalogs, use the list operation to locate a catalog. A single-catalog read and updates to the catalog name, description, or full schema are unavailable. To change a field name or type, add a field and migrate the values. Selection operations are limited to creation and deletion. The API uses JSON. There is no public CSV import or export endpoint. Before you delete a catalog, check messages that reference it and verify your backup. Catalog DELETE permanently removes its data and synchronization history.

Authenticate

Send your Access Key and Secret Key to /authenticate to get an API token. Include these headers on Catalog requests.
API tokens expire after one hour by default. If a token expires and you receive 401, get a new token and retry the request. See API overview for the authentication flow.

Create a catalog and read its items

1. Create a catalog

Create one catalog per request. The first entry in fields must define id as a string.
Supported field types are string, number, boolean, time, geo, object, and array.
  • time accepts an ISO 8601 string or Unix seconds within the safe integer range. Notifly stores it as a UTC ISO 8601 string.
  • geo accepts an array of finite numbers in the order [longitude, latitude]. Longitude ranges from -180 to 180. Latitude ranges from -90 to 90.
  • array accepts an array of strings.

2. Add items

Call POST /items to create a batch of items. Each request can contain up to 50 items.
If any item fails schema validation, the entire request fails and no items are saved.

3. Read the next page of items

GET /items returns 50 items per page in ascending ID order. When there is another page, the response contains data.next_cursor and the Link: <...>; rel="next" header.
  • Pass data.next_cursor unchanged as the cursor query parameter of the next request.
  • A null cursor marks the last page.

Selection filters

A selection stores a subset of catalog items that you can reuse in messages. Filter values must be non-null. If you provide sort_field, also provide sort_order. The default results_limit is 50. If you omit the sort order and field, Notifly randomly chooses up to results_limit items when it creates the selection.

Write methods

For example, update an item by adding and removing values in an array field.
Successful bulk item writes and field or selection changes return 200. Creating a catalog or a single item returns 201.

Responses and errors

Catalog responses use this structure.
On error, data is null and the response includes error.code and error.message. A validation error may include the invalid fields and paths in error.details.
  • For a 400 response, check the project ID format, request schema, and field values before retrying.
  • For a 401 response, get a new API token.
  • For a 403 response, check the project ID and your access permissions.
  • For a 404 response, check the catalog, field, item, or selection name.
  • For a 409 response, check for a duplicate or conflicting resource state. Use a supported list or read operation, or check your own progress records.
  • For a 413 response, split the request into batches smaller than 4 MiB.
  • If a request times out or returns 500, use exponential backoff with jitter. For POST, use a list or read operation to check which resources were created before retrying the missing ones. For items whose full contents can safely be reapplied, use PUT.
Use bulk requests of up to 50 items for migrations. Discuss throughput requirements with Notifly before sustained high-volume writes. Notifly does not publish a shared rate-limit bucket contract like Braze’s for these endpoints.

Limits

Keys stored in an object field cannot contain . or $. Use $add and $remove only as operators to PATCH an array field.

Catalog operations

Check request and response schemas for catalogs, items, fields, and selections.

Migrate catalogs from Braze

Compare authentication, responses, and status codes and plan the migration.