braze-specification

{ "openapi": "3.0.0", "info": { "title": "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, `https://rest.example.braze.com`, 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/)", "version": "1.0.0" }, "servers": [ { "url": "https://rest.iad-01.braze.com", "description": "REST endpoint for instance US-01" }, { "url": "https://rest.iad-01.braze.com", "description": "REST endpoint for instance US-01" }, { "url": "https://rest.iad-02.braze.com", "description": "REST endpoint for instance US-02" }, { "url": "https://rest.iad-03.braze.com", "description": "REST endpoint for instance US-03" }, { "url": "https://rest.iad-04.braze.com", "description": "REST endpoint for instance US-04" }, { "url": "https://rest.iad-05.braze.com", "description": "REST endpoint for instance US-05" }, { "url": "https://rest.iad-06.braze.com", "description": "REST endpoint for instance US-06" }, { "url": "https://rest.iad-08.braze.com", "description": "REST endpoint for instance US-08" }, { "url": "https://rest.fra-01.braze.eu", "description": "REST endpoint for instance EU-01" }, { "url": "https://rest.fra-02.braze.eu", "description": "REST endpoint for instance EU-02" } ], "components": { "responses": { "BadRequest": { "description": "400 Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "401 Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "403 Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "404 Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "429 Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalServerError": { "description": "500 Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Catalogs", "description": "Use the Braze Catalogs Endpoints to add, edit, and manage your catalogs and catalog item details. You can use the asynchronous catalog endpoints to make bulk changes to your catalog.\n\nLooking for guidance on creating a catalog? Check out our article for [creating and using catalogs](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/catalog/)." }, { "name": "Catalogs > Catalog Management" }, { "name": "Catalogs > Catalog Management > Synchronous" }, { "name": "Catalogs > Catalog Items" }, { "name": "Catalogs > Catalog Items > Asynchronous" }, { "name": "Catalogs > Catalog Items > Synchronous" }, { "name": "Email Lists & Addresses", "description": "Using this set of endpoints, you can update a user’s email subscription status, and use the Braze API to set up bi-directional sync between Braze and other email systems or your own database." }, { "name": "Export", "description": "With this collection of endpoints, you can access and export various levels of details on your KPIs, News Feed cards, app sessions, users, segments, campaigns, and Canvases. \n \nMake sure you know your [Braze instance](https://www.braze.com/docs/user_guide/administrative/access_braze/braze_instances/), [API key](https://www.braze.com/docs/api/api_key/), and [API identifier](https://www.braze.com/docs/api/identifier_types/) when building out your parameters and request bodies." }, { "name": "Export > Campaign" }, { "name": "Export > Canvas" }, { "name": "Export > Custom Events" }, { "name": "Export > KPI" }, { "name": "Export > News Feed" }, { "name": "Export > Purchases" }, { "name": "Export > Segment" }, { "name": "Export > Session Analytics" }, { "name": "Export > User Data" }, { "name": "Messages", "description": "The Braze Messaging API provides you with two distinct options for sending messages to your users. You can provide the message contents and configuration in the API request with the `/messages/send` and `/messages/schedule` endpoints. Alternatively, you can manage the details of your message with an API-triggered campaign in the Braze dashboard and just control when and to whom it is sent with the `/campaigns/trigger/send` and `/campaigns/trigger/schedule` endpoints. The following sections will detail the request specification for both methods.\n\nSimilarly to other campaigns, you can limit the number of times a particular user can receive a messaging API campaign by configuring [re-eligibility settings](https://www.braze.com/docs/user_guide/engagement_tools/campaigns/building_campaigns/delivery_types/api_triggered_delivery/#re-eligibility-with-api-triggered-campaigns) in the Braze dashboard. Braze will not deliver API messages to users who haven’t become re-eligible for the campaign regardless of how many API requests are sent.\n\nThe Send Message endpoints allow you to send immediate messages to designated users. If you are targeting a segment, a record of your request will be stored in the **Message Activity Log**. Use the Schedule Message endpoints to send messages at a designated time, and modify or cancel messages that you have already scheduled." }, { "name": "Messages > Live Activities" }, { "name": "Messages > Schedule Mesages" }, { "name": "Messages > Send Messages" }, { "name": "Preference Center", "description": "Use the endpoints in this section to build a preference center, which is a Braze-hosted website that can display your user’s subscription state and subscription group statuses. Using HTML and CSS, your developer team can build your preference center so that the styling of the page matches your brand guidelines.\n\nCheck out [ Preference center overview](https://www.braze.com/docs/user_guide/message_building_by_channel/email/preference_center/overview/) for more details on how to create and customize your preference center." }, { "name": "SCIM", "description": "The [System for Cross-domain Identity Management (SCIM)](http://www.simplecloud.info/) specification is designed to make managing user identities in cloud-based applications and services easier by providing a defined schema for representing users and groups. Use the Braze SCIM endpoints to manage automated user provisioning." }, { "name": "SMS", "description": "Use the Braze SMS Endpoints to manage your users’ phone numbers in your subscription groups." }, { "name": "Subscription Groups", "description": "Use the Subscription Group REST APIs to programmatically manage the subscription groups that you have stored on the Braze dashboard, on the **Subscription Group** page. This applies to both SMS and email subscription groups. \n \nLooking for guidance on creating subscription groups? Check out our articles for [SMS subscription groups](https://www.braze.com/docs/user_guide/message_building_by_channel/sms/sms_subscription_group//) and [email subscription groups](https://www.braze.com/docs/user_guide/message_building_by_channel/email/managing_user_subscriptions/)." }, { "name": "Subscription Groups > Email" }, { "name": "Subscription Groups > SMS and WhatsApp" }, { "name": "Templates", "description": "Using the Template endpoints, you can create and manage your templates for email and Content Blocks. \n \nLooking for more guidance on creating templates for email and Content Blocks? Check out our dedicated for [Email Templates section](https://www.braze.com/docs/user_guide/message_building_by_channel/email/templates/) and [Content Blocks article](https://www.braze.com/docs/user_guide/engagement_tools/templates_and_media/content_blocks/)." }, { "name": "Templates > Content Blocks", "description": "Content Blocks are an Email Templating feature that allow you to: \n- Create a consistent look and feel to your Email campaigns using Content Blocks as Headers and Footers.\n- Distribute the same offer codes through different channels.\n- Create pre-defined assets that can be used to build messages with consistent information and assets.\n- Copy entire message bodies to other messages.\n\nYou can edit Content Blocks in the Templates & Media section of the Braze UI, or here, via API." }, { "name": "Templates > Email Templates" }, { "name": "User Data", "description": "The Braze User Data endpoints allow you to track information about your users by logging data about them that comes from outside your mobile app. You can also use this API to delete users for testing or other purposes.\n\nAll API endpoints have a data payload limit of 4 MB. Attempts to post more data than 4 MB will fail with an HTTP 413 Request Entity Too Large.\n\nThe examples in this section contain the URL [https://rest.iad-01.braze.com](https://rest.iad-01.braze.com), but you may need to use a different endpoint URL (for example, if you're hosted in the Braze EU data center or have a dedicated Braze installation). Your Braze customer success manager will inform you if you should use a different endpoint URL." }, { "name": "User Data > External ID Migration", "description": "The External ID Migration API allows you to rename existing external IDs (creating a new primary ID and deprecating the existing ID) and remove deprecated IDs post-migration. <br><br> We've architected this solution to allow multiple External IDs in order to support a migration period whereby older versions of your apps still in the wild that use the previous External ID naming schema don’t break. We highly recommend removing deprecated External IDs once your old naming schema is no longer in use." } ], "paths": { "/catalogs/{catalog_name}": { "delete": { "tags": ["Catalogs > Catalog Management > Synchronous"], "summary": "Delete catalog", "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. |", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" }, { "name": "catalog_name", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/catalogs": { "get": { "tags": ["Catalogs > Catalog Management > Synchronous"], "summary": "List 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 ```", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": ["Catalogs > Catalog Management > Synchronous"], "summary": "Create catalog", "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. |", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "catalogs": [ { "name": "restaurants", "description": "My Restaurants", "fields": [{ "name": "id", "type": "string" }] } ] }, "properties": { "catalogs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } } } } } } } } }, "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/catalogs/{catalog_name}/items": { "delete": { "tags": ["Catalogs > Catalog Items > Asynchronous"], "summary": "Delete multiple catalog 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. |", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" }, { "name": "catalog_name", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "items": [{ "id": "restaurant1" }] }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } } } }, "patch": { "tags": ["Catalogs > Catalog Items > Asynchronous"], "summary": "Edit multiple catalog 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. |", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "items": [{ "id": "restaurant1" }] }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } } }, "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" }, { "name": "catalog_name", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": ["Catalogs > Catalog Items > Asynchronous"], "summary": "Create multiple catalog 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. |", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "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" } ] }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "Name": { "type": "string" }, "City": { "type": "string" }, "Cuisine": { "type": "string" }, "Rating": { "type": "integer" }, "Loyalty_Program": { "type": "boolean" }, "Created_At": { "type": "string", "format": "date-time" } } } } } } } } }, "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "example": "Bearer {{api_key}}" }, { "name": "catalog_name", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": ["Catalogs > Catalog Items > Asynchronous"], "summary": "Update multiple catalog 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