braze-specification

{ "info": { "_postman_id": "cd81c470-a7cc-412e-9560-79f90723c9e0", "name": "Braze Endpoints", "description": "# Braze API overview\n\nBraze provides a high-performance REST API to allow you to track users, send messages, export data, and more. This reference article covers what a REST API is, the terminology, a brief overview of API keys, and API limits.\n\nA REST API is a way to programmatically transfer information over the web using a predefined schema. Braze has created many different endpoints which perform various actions and/or return various data.\n\nBraze manages a number of different instances for our dashboard and REST Endpoints. When your account is provisioned you will log in to one of the following URLs. Use the correct REST endpoint based on which instance you are provisioned to. If you are unsure, open a [support ticket](https://www.braze.com/docs/braze_support/) or use the following table to match the URL of the dashboard you use to the correct REST Endpoint.\n\n> Customers using Braze’s EU database should use the `https://rest.fra-01.braze.eu/` endpoint. This endpoint will be used when configuring the Braze [iOS](https://www.braze.com/docs/developer_guide/platform_integration_guides/ios/initial_sdk_setup/completing_integration/#compile-time-endpoint-configuration-recommended), [Android](https://www.braze.com/docs/developer_guide/platform_integration_guides/android/initial_sdk_setup/android_sdk_integration/#step-2-configure-the-braze-sdk-in-brazexml), and [Web](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/initial_sdk_setup/#step-2-initialize-braze) SDKs. \n \n\n## Braze Instances\n\n| Instance | Dashboard URL | REST Endpoint |\n| --- | --- | --- |\n| US-01 | `https://dashboard.braze.com` or <br>`https://dashboard-01.braze.com` | `https://rest.iad-01.braze.com` |\n| US-02 | `https://dashboard-02.braze.com` | `https://rest.iad-02.braze.com` |\n| US-03 | `https://dashboard-03.braze.com` | `https://rest.iad-03.braze.com` |\n| US-04 | `https://dashboard-04.braze.com` | `https://rest.iad-04.braze.com` |\n| US-05 | `https://dashboard-05.braze.com` | `https://rest.iad-05.braze.com` |\n| US-06 | `https://dashboard-06.braze.com` | `https://rest.iad-06.braze.com` |\n| US-07 | `https://dashboard-07.braze.com` | `https://rest.iad-07.braze.com` |\n| US-08 | `https://dashboard-08.braze.com` | `https://rest.iad-08.braze.com` |\n| EU-01 | `https://dashboard-01.braze.eu` | `https://rest.fra-01.braze.eu` |\n| EU-02 | `https://dashboard-02.braze.eu` | `https://rest.fra-02.braze.eu` |\n\n# Using Braze's Postman collection\n\nIf you have a Postman account (you can download macOS, Windows, and Linux versions from the [Postman website](https://www.getpostman.com/) ), you can open our Postman documentation in your own Postman app by clicking the orange **Run in Postman** button. You can then [create an environment](https://www.braze.com/docs/api/postman_collection/#setting-up-your-postman-environment), or use our Braze REST API environment as a template, and edit the available `POST` and `GET` requests to suit your own needs.\n\n## Setting up your Postman environment\n\nThe Braze Postman Collection uses a templating variable, `{{instance_url}}`, to substitute the REST API URL of your Braze instance into the pre-built requests, and the `{{api_key}}` variable for your API Key. Rather than having to manually edit all requests in the Collection, you can set up this variable in your Postman environment. You can either select our templated environment (Braze REST API Environment Template) from the dropdown and replace the variable values with your own, or you can set up your own environment.\n\nTo set up your own environment, perform the following steps:\n\n1. From the **Workspaces** tab, select **Environments**.\n \n2. Click the **+** plus button to create a new environment.\n \n3. Give this environment a name (e.g., “Braze API Requests”) and add keys for `instance_url` and `api_key` with values corresponding to your [Braze instance](https://www.braze.com/docs/developer_guide/rest_api/basics/#endpoints) and [Braze REST API Key](https://www.braze.com/docs/api/api_key/).\n \n4. Click **Save**.\n \n\n## Using the pre-built requests from the collection\n\nOnce you have configured your environment. You can use any of the pre-built requests in the collection as a template for building new API requests. To start using one of the pre-built requests, click on it within the **Collections** menu of Postman. This will open the request as a new tab in the main window of the Postman app.\n\nIn general, there are two types of requests that Braze’s API endpoints accept - `GET` and `POST`. Depending on which `HTTP` method the endpoint uses, you’ll need to edit the pre-built request differently.\n\n### Edit a POST request\n\nWhen editing a `POST` request, open the request and navigate to the **Body** section in the request editor. For readability, select the **raw** radio button to format the `JSON` request body.\n\n### Edit a GET request\n\nWhen editing a `GET` request, edit the parameters passed in the request URL. To do so, select the **Params** tab and edit the key-value pairs in the fields that appear.\n\n## Send your request\n\nOnce your API request is ready, click **Send**. The request sends and the response data populates in a section underneath the request editor. From here, you can view the raw data returned from Braze’s API, see the HTTP response code, see how long the request took to process, and view header information.\n\nThe following documentation can be found on the Braze documentation site:\n\n- [Object & filter specifications](https://www.braze.com/docs/api/objects_filters/)\n \n- [API key overview](https://www.braze.com/docs/api/api_key/)\n \n- [API identifier types](https://www.braze.com/docs/api/identifier_types/)\n \n- [Errors & responses](https://www.braze.com/docs/api/errors/)\n \n- [Parameters](https://www.braze.com/docs/api/parameters)\n \n- [Data retention](https://www.braze.com/docs/api/data_retention/)\n \n- [API network connectivity issues](https://www.braze.com/docs/api/network_connectivity_issues)\n \n- [Rate limits](https://www.braze.com/docs/api/api_limits/)\n \n- [API campaigns](https://www.braze.com/docs/api/api_campaigns/)", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "24010587" }, "item": [ { "name": "Catalogs", "item": [ { "name": "Catalog Management", "item": [ { "name": "Synchronous", "item": [ { "name": "Delete catalog", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}"] }, "description": "> Use this endpoint to delete a catalog. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.delete` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Response\n\nThere are two status code responses for this endpoint: `200` and `404`.\n\n### Example success response\n\nThe status code `200` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `404` could return the following response body. Refer to [Troubleshooting](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/delete_catalog/#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"catalog-not-found\",\n \"message\": \"Could not find catalog\",\n \"parameters\": [\n \"catalog_name\"\n ],\n \"parameter_values\": [\n \"restaurants\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-not-found` | Check that the catalog name is valid. |" }, "response": [] }, { "name": "List catalogs", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs"] }, "description": "> Use this endpoint to return a list of catalogs in a workspace. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.get` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path and request parameters\n\nThere are no path or request parameters for this endpoint.\n\n## Example request\n\n```\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n ```\n\n## Response\n\n### Example success response\n\nThe status code `200` could return the following response body.\n\n``` json\n{\n \"catalogs\": [\n {\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ],\n \"name\": \"restaurants\",\n \"num_items\": 10,\n \"updated_at\": \"2022-11-02T20:04:06.879+00:00\"\n },\n {\n \"description\": \"My Catalog\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"string_field\",\n \"type\": \"string\"\n },\n {\n \"name\": \"number_field\",\n \"type\": \"number\"\n },\n {\n \"name\": \"boolean_field\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"time_field\",\n \"type\": \"time\"\n },\n ],\n \"name\": \"my_catalog\",\n \"num_items\": 3,\n \"updated_at\": \"2022-11-02T09:03:19.967+00:00\"\n },\n ],\n \"message\": \"success\"\n}\n\n ```" }, "response": [] }, { "name": "Create catalog", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs"] }, "description": "> Use this endpoint to create a catalog. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.create` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalogs` | Required | Array | An array that contains catalog objects. Only one catalog object is allowed for this request. |\n\n### Catalog object parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `name` | Required | String | The name of the catalog that you want to create. |\n| `description` | Required | String | The description of the catalog that you want to create. |\n| `fields` | Required | Array | An array of objects where the object contains keys `name` and `type`. |\n\n## Example request\n\n```\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"catalogs\": [\n {\n \"name\": \"restaurants\",\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ]\n }\n ]\n}'\n\n ```\n\n## Response\n\nThere are two status code responses for this endpoint: `201` and `400`.\n\n### Example success response\n\nThe status code `201` could return the following response body.\n\n``` json\n{\n \"catalogs\": [\n {\n \"description\": \"My Restaurants\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Name\",\n \"type\": \"string\"\n },\n {\n \"name\": \"City\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Cuisine\",\n \"type\": \"string\"\n },\n {\n \"name\": \"Rating\",\n \"type\": \"number\"\n },\n {\n \"name\": \"Loyalty_Program\",\n \"type\": \"boolean\"\n },\n {\n \"name\": \"Created_At\",\n \"type\": \"time\"\n }\n ],\n \"name\": \"restaurants\",\n \"num_items\": 0,\n \"updated_at\": \"2022-11-02T20:04:06.879+00:00\"\n }\n ],\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"catalog-name-already-exists\",\n \"message\": \"A catalog with that name already exists\",\n \"parameters\": [\n \"name\"\n ],\n \"parameter_values\": [\n \"restaurants\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-array-invalid` | `catalogs` must be an array of objects. |\n| `catalog-name-already-exists` | Catalog with that name already exists. |\n| `catalog-name-too-large` | Character limit for a catalog name is 250. |\n| `description-too-long` | Character limit for description is 250. |\n| `field-names-not-unique` | The same field name is referenced twice. |\n| `field-names-too-large` | Character limit for a field name is 250. |\n| `id-not-first-column` | The `id` must be the first field in the array. Check that the type is a string. |\n| `invalid_catalog_name` | Catalog name can only include letters, numbers, hyphens, and underscores. |\n| `invalid-field-names` | Fields can only include letters, numbers, hyphens, and underscores. |\n| `invalid-field-types` | Make sure the field types are valid. |\n| `invalid-fields` | `fields` is not formatted correctly. |\n| `reached-company-catalogs-limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. |\n| `too-many-catalog-atoms` | You can only create one catalog per request. |\n| `too-many-fields` | Number of fields limit is 30. |", "body": { "mode": "raw", "raw": "{\"catalogs\":[{\"name\":\"restaurants\",\"description\":\"My Restaurants\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}]}" } }, "response": [] } ] } ] }, { "name": "Catalog Items", "item": [ { "name": "Asynchronous", "item": [ { "name": "Delete multiple catalog items", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}", "items"] }, "description": "> Use this endpoint to delete multiple items in your catalog. \n \n\nEach request can support up to 50 items. This endpoint is asynchronous.\n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.delete_items` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `items` | Required | Array | An array that contains item objects. The item objects should contain an `id` referencing the items Braze should delete. Up to 50 item objects are allowed per request. |\n\n## Example request\n\n```\ncurl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\"id\": \"restaurant1\"},\n {\"id\": \"restaurant2\"},\n {\"id\": \"restaurant3\"}\n ]\n}'\n\n ```\n\n## Response\n\nThere are three status code responses for this endpoint: `202`, `400`, and `404`.\n\n### Example success response\n\nThe status code `202` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"items-missing-ids\",\n \"message\": \"There are 1 item(s) that do not have ids\",\n \"parameters\": [],\n \"parameter_values\": []\n }\n ],\n \"message\": \"Invalid Request\",\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-not-found` | Check that the catalog name is valid. |\n| `ids-too-large` | Item IDs can't be more than 250 characters. |\n| `ids-not-unique` | Check that the item IDs are unique in the request. |\n| `ids-not-strings` | Item IDs must be of type string. |\n| `items-missing-ids` | Some items don't have item IDs. Check that each item has an item ID. |\n| `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. |\n| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |" }, "response": [] }, { "name": "Edit multiple catalog items", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}", "items"] }, "description": "> Use this endpoint to delete multiple items in your catalog. \n \n\nEach request can support up to 50 items. This endpoint is asynchronous.\n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.update_items` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog. Up to 50 item objects are allowed per request. |\n\n## Example request\n\n```\ncurl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": {\n \"$add\": [\n \"Biscuits\",\n \"Coleslaw\"\n ],\n \"$remove\": [\n \"French Fries\"\n ]\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"City\": \"San Francisco\",\n \"Rating\": 2,\n \"Top_Dishes\": [\n \"Buffalo Wings\",\n \"Philly Cheesesteak\"\n ]\n }\n ]\n}'\n\n ```\n\n> **Note:** The $`add` and `$remove` operators are only applicable to array type fields, and are only supported by PATCH endpoints. \n \n\n## Response\n\nThere are three status code responses for this endpoint: `202`, `400`, and `404`.\n\n### Example success response\n\nThe status code `202` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-not-found` | Check that the catalog name is valid. |\n| `ids-too-large` | Item IDs can't be more than 250 characters. |\n| `ids-not-strings` | Item IDs must be of type string. |\n| `ids-not-unique` | Item IDs must be unique in the request. |\n| `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. |\n| `invalid-fields` | Confirm that all fields you are sending in the API request already exist in the catalog. This is not related to the ID field mentioned in the error. |\n| `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. |\n| `items-missing-ids` | Some items don't have item IDs. Check that each item has an item ID. |\n| `item-array-invalid` | `items` must be an array of objects. |\n| `items-too-large` | Item values can't exceed 5,000 characters. |\n| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |\n| `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. |\n| `unable-to-coerce-value` | Item types can't be converted. |", "body": { "mode": "raw", "raw": "{\"items\":[{\"id\":\"restaurant1\"}]}" } }, "response": [] }, { "name": "Create multiple catalog items", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}", "items"] }, "description": "> Use this endpoint to create multiple items in your catalog. \n \n\nEach request can support up to 50 items. This endpoint is asynchronous.\n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.add_items` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `items` | Required | Array | An array that contains item objects. The item objects should contain all of the fields in the catalog. Up to 50 item objects are allowed per request. |\n\n## Example request\n\n```\ncurl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Created_At\": \"2022-11-01T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant2\",\n \"Name\": \"Restaurant2\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 10,\n \"Loyalty_Program\": true,\n \"Location\": {\n \"Latitude\": 40.7413,\n \"Longitude\": -73.9764\n },\n \"Top_Dishes\": [\n \"Hot Dog\",\n \"French Fries\"\n ],\n \"Created_At\": \"2022-11-02T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant3\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 3,\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 40.7489,\n \"Longitude\": -73.9972\n },\n \"Top_Dishes\": [\n \"Buffalo Wings\",\n \"Philly Cheesesteak\"\n ],\n \"Created_At\": \"2022-11-03T09:03:19.967+00:00\"\n }\n ]\n}'\n\n ```\n\n## Response\n\nThere are three status code responses for this endpoint: `202`, `400`, and `404`.\n\n### Example success response\n\nThe status code `202` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"fields-do-not-match\",\n \"message\": \"Fields do not match with fields on the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant2\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-not-found` | Check that the catalog name is valid. |\n| `ids-not-strings` | Item IDs must be of type string. |\n| `ids-not-unique` | Item IDs must be unique in the request. |\n| `ids-too-large` | Item IDs can't be more than 250 characters. |\n| `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. |\n| `invalid-fields` | Confirm that the fields in the request exist in the catalog. |\n| `invalid-keys-in-value-object` | Item object keys can't include `.` or `$`. |\n| `item-array-invalid` | `items` must be an array of objects. |\n| `items-missing-ids` | Some items don't have item IDs. Check that each item has an item ID. |\n| `items-too-large` | Item values can't exceed 5,000 characters. |\n| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |\n| `too-deep-nesting-in-value-object` | Item objects can't have more than 50 levels of nesting. |\n| `unable-to-coerce-value` | Item types can't be converted. |", "body": { "mode": "raw", "raw": "{\"items\":[{\"id\":\"restaurant1\",\"Name\":\"Restaurant1\",\"City\":\"New York\",\"Cuisine\":\"American\",\"Rating\":5,\"Loyalty_Program\":true,\"Created_At\":\"2022-11-01T09:03:19.967+00:00\"}]}" } }, "response": [] }, { "name": "Update multiple catalog items", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"items\": [\n {\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n }\n ]\n}" }, "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}", "items"] }, "description": "> Use this endpoint to update multiple items in your catalog. \n \n\nIf a catalog item doesn’t exist, this endpoint will create the item in your catalog. Each request can support up to 50 catalog items. This endpoint is asynchronous.\n\n## Prerequisites\n\nTo use this endpoint, you'll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.replace_item` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 16,000 requests per minute between all asynchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `items` | Required | Array | An array that contains item objects. Each object must have an ID. The item objects should contain fields that exist in the catalog. Up to 50 item objects are allowed per request. |\n\n## Example request\n\n``` json\ncurl --location --request PUT 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY' \\\n--data-raw '{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant\",\n \"Loyalty_Program\": false,\n \"Location\": {\n \"Latitude\": 33.6112,\n \"Longitude\": -117.8711\n },\n \"Top_Dishes\": [\n \"Hamburger\",\n \"Deluxe Cheeseburger\"\n ],\n \"Open_Time\": \"2021-09-03T09:03:19.967+00:00\"\n },\n {\n \"id\": \"restaurant3\",\n \"City\": \"San Francisco\",\n \"Rating\": 2,\n \"Top_Dishes\": [\n \"Hot Dog\",\n \"French Fries\"\n ]\n }\n ]\n}'\n\n ```\n\n## Response\n\nThere are three status code responses for this endpoint: `202`, `400`, and `404`.\n\n### Example success response\n\nThe status code `202` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"invalid-fields\",\n \"message\": \"Some of the fields given do not exist in the catalog\",\n \"parameters\": [\n \"id\"\n ],\n \"parameter_values\": [\n \"restaurant1\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog_not_found` | Check that the catalog name is valid. |\n| `ids_not_string` | Confirm that each item ID is a string. |\n| `ids_not_unique` | Check that each item ID is unique. |\n| `ids_too_large` | Character limit for each item ID is 250 characters. |\n| `item_array_invalid` | `items` must be an array of objects. |\n| `items_missing_ids` | Some items don't have item IDs. Confirm that each item has an ID. |\n| `items_too_large` | Item values can't exceed 5,000 characters. |\n| `invalid_ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. |\n| `invalid_fields` | Confirm that the fields in the request exist in the catalog. |\n| `invalid_keys_in_value_object` | Item object keys can't include `.` or `$`. |\n| `too_deep_nesting_in_value_object` | Item objects can't have more than 50 levels of nesting. |\n| `request_includes_too_many_items` | Your request has too many items. The item limit per request is 50. |\n| `unable_to_coerce_value` | Item types can't be converted. |" }, "response": [] } ] }, { "name": "Synchronous", "item": [ { "name": "Delete a catalog item", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}", "protocol": "https", "host": ["{{instance_url}}"], "path": [ "catalogs", "{catalog_name}", "items", "{item_id}" ] }, "description": "> Use this endpoint to delete an item in your catalog. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.delete_item` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n| `item_id` | Required | String | The ID of the catalog item. |\n\n## Request parameters\n\nThere is no request body for this endpoint.\n\n## Example request\n\n```\ncurl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n ```\n\n## Response\n\nThere are three status code responses for this endpoint: `202`, `400`, and `404`.\n\n### Example success response\n\nThe status code `202` could return the following response body.\n\n``` json\n{\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"item-not-found\",\n \"message\": \"Could not find item\",\n \"parameters\": [\n \"item_id\"\n ],\n \"parameter_values\": [\n \"restaurant34\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support](https://www.braze.com/docs/support_contact/). |\n| `catalog-not-found` | Check that the catalog name is valid. |\n| `item-not-found` | Check that the item to be deleted exists in your catalog. |" }, "response": [] }, { "name": "List catalog item details", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items/{item_id}", "protocol": "https", "host": ["{{instance_url}}"], "path": [ "catalogs", "{catalog_name}", "items", "{item_id}" ] }, "description": "> Use this endpoint to return a catalog item and its content. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.get_item` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n| `item_id` | Required | String | The ID of the catalog item. |\n\n## Request parameters\n\nThere is no request body for this endpoint.\n\n## Example request\n\n```\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n ```\n\n## Response\n\nThere are two status code responses for this endpoint: `200` and `404`.\n\n### Example success response\n\nThe status code `200` could return the following response body.\n\n``` json\n{\n \"items\": [\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-01T09:03:19.967Z\"\n }\n ],\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `404` could return the following response. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.\n\n``` json\n{\n \"errors\": [\n {\n \"id\": \"item-not-found\",\n \"message\": \"Could not find item\",\n \"parameters\": [\n \"item_id\"\n ],\n \"parameter_values\": [\n \"restaurant34\"\n ]\n }\n ],\n \"message\": \"Invalid Request\"\n}\n\n ```\n\n## Troubleshooting\n\nThe following table lists possible returned errors and their associated troubleshooting steps, if applicable.\n\n| Error | Troubleshooting |\n| --- | --- |\n| `catalog-not-found` | Check that the catalog name is valid. |\n| `item-not-found` | Check that the item is in the catalog. |" }, "response": [] }, { "name": "List multiple catalog item details", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" } ], "url": { "raw": "https://{{instance_url}}/catalogs/{catalog_name}/items", "protocol": "https", "host": ["{{instance_url}}"], "path": ["catalogs", "{catalog_name}", "items"] }, "description": "> Use this endpoint to return multiple catalog items and their content. \n \n\n## Prerequisites\n\nTo use this endpoint, you’ll need an [API key](https://braze.com/docs/api/api_key/) with the `catalogs.get_items` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Path parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `catalog_name` | Required | String | Name of the catalog. |\n\n## Query parameters\n\nNote that each call to this endpoint will return 50 items. For a catalog with more than 50 items, use the `Link` header to retrieve the data on the next page as shown in the following example response.\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `cursor` | Optional | String | Determines the pagination of the catalog items. |\n\n## Request parameters\n\nThere is no request body for this endpoint.\n\n## Example requests\n\n### Without cursor\n\n```\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n ```\n\n### With cursor\n\n```\ncurl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items?cursor=c2tpcDow' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR-REST-API-KEY'\n\n ```\n\n## Response\n\nThere are three status code responses for this endpoint: `200`, `400`, and `404`.\n\n### Example success response\n\nThe status code `200` could return the following response header and body.\n\n> \n**Note:** The `Link` header won't exist if the catalog has less than or equal to 50 items. For calls without a cursor, `prev` will not show. When looking at the last page of items, `next` will not show. \n \n \n\n```\nLink: </catalogs/all_restaurants/items?cursor=c2tpcDow>; rel=\"prev\",</catalogs/all_restaurants/items?cursor=c2tpcDoxMDA=>; rel=\"next\"\n\n ```\n\n``` json\n{\n \"items\": [\n {\n \"id\": \"restaurant1\",\n \"Name\": \"Restaurant1\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n },\n {\n \"id\": \"restaurant2\",\n \"Name\": \"Restaurant2\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 10,\n \"Loyalty_Program\": true,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n },\n {\n \"id\": \"restaurant3\",\n \"Name\": \"Restaurant3\",\n \"City\": \"New York\",\n \"Cuisine\": \"American\",\n \"Rating\": 5,\n \"Loyalty_Program\": false,\n \"Open_Time\": \"2022-11-02T09:03:19.967Z\"\n }\n ],\n \"message\": \"success\"\n}\n\n ```\n\n### Example error response\n\nThe status code `400` could return the following response body. Refer to [Troubleshooting](#tro