> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with the Catalog REST API

> Authenticate, manage catalog data, page through items, and handle write errors.

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`.

> [!WARNING]
>
> 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.

```text theme={null}
/v1/projects/{projectId}/catalogs
```

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.

| Resource | Supported operations |
| - | - |
| Catalogs | Create, list, and permanently delete. |
| Fields | Add and delete. |
| Items | Create, read, replace, update selected fields, and delete individual items or batches. |
| Selections | Create and delete. |

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.

```http theme={null}
Authorization: Bearer <auth-token>
Content-Type: application/json
```

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](https://docs.notifly.tech/en/api-reference/getting-started.md) 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`.

```json theme={null}
{
  "catalogs": [
    {
      "name": "products",
      "description": "Product data for message personalization",
      "data_classification": "non_personal",
      "fields": [
        { "name": "id", "type": "string" },
        { "name": "name", "type": "string" },
        { "name": "price", "type": "number" },
        { "name": "tags", "type": "array" }
      ]
    }
  ]
}
```

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.

```json theme={null}
{
  "items": [
    {
      "id": "sku-1001",
      "name": "Cotton shirt",
      "price": 39000,
      "tags": ["summer", "shirt"]
    }
  ]
}
```

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.

| Field type | Operators |
| - | - |
| `string` | `equals`, `does not equal` |
| `number` | `equals`, `does not equal`, `greater than`, `less than` |
| `boolean` | `is` |
| `time` | `before`, `after` |
| `array` | `includes value`, `does not include value` |
| `geo`, `object` | No filter operators |

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

| Method | Operation | What to check before retrying |
| - | - | - |
| `POST` | Creates a new resource. | An existing ID returns `409`. |
| `PUT` | Replaces an item in full, or creates it if the ID does not exist. | Fields omitted from the request are removed. |
| `PATCH` | Changes the supplied fields of an existing item. | A missing ID returns `404`. Use `$add` and `$remove` for array fields. |
| `DELETE` | Deletes the specified resource. | A missing resource returns `404`. |

For example, update an item by adding and removing values in an array field.

```json theme={null}
{
  "items": [
    {
      "id": "sku-1001",
      "tags": {
        "$add": ["sale"],
        "$remove": ["summer"]
      }
    }
  ]
}
```

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.

```json theme={null}
{
  "data": {},
  "error": null
}
```

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`.

> [!NOTE]
>
> 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

| Limit | Maximum |
| - | - |
| Active catalogs per project | 20 |
| Fields per API catalog, including `id` | 500 |
| Fields added per request | 50 |
| Items written or deleted per request | 50 |
| Single item size | 1 MiB |
| Single catalog size | 2 GiB |
| Combined size of active catalogs per project | 15 GiB |
| Characters per string value | 5,000 |
| Strings per array value | 100 |
| Nesting depth for `object` and `array` | 50 |
| Selections per catalog | 30 |
| Filters per selection request | 4 |

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

> [card] [Catalog operations](https://docs.notifly.tech/en/api-reference/catalog/list-api-catalogs.md)
>
> Check request and response schemas for catalogs, items, fields, and selections.

> [card] [Migrate catalogs from Braze](https://docs.notifly.tech/en/developer-guide/migration/braze-catalogs.md)
>
> Compare authentication, responses, and status codes and plan the migration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.