diff --git a/_docs/_api/endpoints/catalogs.md b/_docs/_api/endpoints/catalogs.md index 095773cdb62..c72fab6ecb6 100644 --- a/_docs/_api/endpoints/catalogs.md +++ b/_docs/_api/endpoints/catalogs.md @@ -9,18 +9,18 @@ description: "This landing page lists the Braze Catalogs Endpoints." page_type: landing guide_top_header: "Catalogs Endpoints" -guide_top_text: "Use the Braze Catalogs Endpoints to add, edit, and manage your catalogs and catalog item details. You can use the synchronous catalog endpoints to make bulk changes to your catalog. To receive a confirmation that a change to your catalog has been received and processed, use the asynchronous or synchronous catalog item endpoints.

Looking for guidance on creating a catalog? Check out our article for creating and using catalogs." +guide_top_text: "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.

Looking for guidance on creating a catalog? Check out our article for creating and using catalogs." -guide_featured_title: "Catalogs Endpoints

" +guide_featured_title: "Catalog Management Endpoints

" guide_featured_list: - name: "DELETE: Delete Catalog" - link: /docs/api/endpoints/catalogs/catalogs/synchronous/delete_catalog/ + link: /docs/api/endpoints/catalogs/catalog_management/synchronous/delete_catalog/ fa_icon: fas fa-pen-square - name: "GET: List Catalogs" - link: /docs/api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs/ + link: /docs/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs/ fa_icon: fas fa-list-ul - name: "POST: Create Catalog" - link: /docs/api/endpoints/catalogs/catalogs/synchronous/post_create_catalog/ + link: /docs/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog/ fa_icon: fas fa-check optional_guide_menu_title: "Catalog Items Endpoints" diff --git a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md index cbf45227a75..76188bdc61f 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md @@ -12,10 +12,10 @@ description: "This article outlines details about the Delete Multiple Catalog It {% api %} # Delete multiple catalog items {% apimethod delete %} -/catalogs/catalog_name/items +/catalogs/{catalog_name}/items {% endapimethod %} -Use this endpoint to delete multiple items in your catalog. Each request can support up to 50 items. +Use this endpoint to delete multiple items in your catalog. Each request can support up to 50 items. This endpoint is asynchronous. {% alert important %} Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. @@ -27,69 +27,80 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints. -## Request body +## Path parameters -```json -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -{ - "items": [ (max of 50 items) - { - "id": (required, item id) - }, - { - "id": (required, item id) - }, - ] -} -``` +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalog_name` | Required | String | Name of the catalog. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -### Request parameters +## Request parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the imported catalog.| +| `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. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} ## Example request ``` -https://rest.iad-03.braze.com/catalogs/catalog_name/items +curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' \ +--data-raw '{ + "items": [ + {"id": "restaurant1"}, + {"id": "restaurant2"}, + {"id": "restaurant3"} + ] +}' +``` + +## Response + +There are three status code responses for this endpoint: `202`, `400`, and `404`. + +### Example success response + +The status code `202` could return the following response body. + +```json +{ + "message": "success" +} ``` -## Example error response +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ { - "id": "invalid-ids", - "message": "Item ids can only include letters, numbers, hyphens, and underscores", - "parameters": ["id"], - "parameter_values": ["item_id"] - }, - { - "id": "items-missing-ids", - "message": "There are 5 items that do not have ids", - "parameters": [], - "parameter_values": [] + "id": "items-missing-ids", + "message": "There are 1 item(s) that do not have ids", + "parameters": [], + "parameter_values": [] } - ] + ], + "message": "Invalid Request", } ``` ## Troubleshooting -The following table lists possible returned errors and their associated troubleshooting steps, if applicable. +The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | +| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `ids-not-unique` | Check that the item IDs are unique in the request. | -| `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | -| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | +| `ids-not-strings` | Item IDs must be of type string. | +| `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | {: .reset-td-br-1 .reset-td-br-2} {% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md index 2d40ffbf2a7..6d0c951b2a0 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md @@ -13,10 +13,10 @@ description: "This article outlines details about the Edit Multiple Catalog Item {% api %} # Edit multiple catalog items {% apimethod patch %} -/catalogs/catalog_name/items +/catalogs/{catalog_name}/items {% endapimethod %} -Use this endpoint to edit multiple items in your catalog. Each request can support up to 50 items. +Use this endpoint to edit multiple items in your catalog. Each request can support up to 50 items. This endpoint is asynchronous. {% alert important %} Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. @@ -28,74 +28,76 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints. -## Request body +## Path parameters -``` -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -``` - -```json -{ - "items": [ (max of 50 items) - { - "id": (required, item id), - "count": (required, item count), - }, - { - "id": (required, item id), - "count": (required, item count), - }, - { - "id": (required, item id), - "count": (required, item count), - } - ] -} -``` +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalog_name` | Required | String | Name of the catalog. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -### Request parameters +## Request parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `item_id` | Required | String | Item ID for a catalog item. | +| `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. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} ## Example request + ``` -curl --location --request PATCH 'https://rest.iad-01.braze.com/catalogs/catalog_name/items' \ +curl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ - "items": [ - { - "id": "item_0", - "count": 1, - }, - { - "id": "item_1", - "count": 2, - }, - { - "id": "item_2", - "count": 3, - } - ] + "items": [ + { + "id": "restaurant1", + "Name": "Restaurant", + "Loyalty_Program": false, + "Open_Time": "2021-09-03T09:03:19.967+00:00" + }, + { + "id": "restaurant3", + "City": "San Francisco", + "Rating": 2 + } + ] +}' +``` + +## Response + +There are three status code responses for this endpoint: `202`, `400`, and `404`. + +### Example success response + +The status code `202` could return the following response body. + +```json +{ + "message": "success" } ``` -## Example error response +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ { - "id": "catalog-not-found", - "message": "Could not find catalog", - "parameters": ["catalog_name"], - "parameter_values": ["catalog_name"] + "id": "invalid-fields", + "message": "Some of the fields given do not exist in the catalog", + "parameters": [ + "id" + ], + "parameter_values": [ + "restaurant1" + ] } - ] + ], + "message": "Invalid Request" } ``` @@ -106,12 +108,14 @@ The following table lists possible returned errors and their associated troubles | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | +| `item-array-invalid` | `items` must be an array of objects. | +| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `ids-too-large` | Item IDs can't be more than 250 characters. | -| `items-too-large` | Item values can't exceed 5,000 characters. | | `ids-not-unique` | Item IDs must be unique in the request. | -| `request-includes-too-many-items` | Your request has too many items. The maximum is 50. | +| `ids-not-strings` | Item IDs must be of type string. | | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | +| `items-too-large` | Item values can't exceed 5,000 characters. | | `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `unable-to-coerce-value` | Item types can't be converted. | {: .reset-td-br-1 .reset-td-br-2} diff --git a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk.md b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk.md index 98bfe9c03b2..367ca81475c 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/asynchronous/post_create_catalog_items_bulk.md @@ -12,10 +12,10 @@ description: "This article outlines details about the Create Multiple Catalog It {% api %} # Create multiple catalog items {% apimethod post %} -/catalogs/catalog_name/items +/catalogs/{catalog_name}/items {% endapimethod %} -Use this endpoint to create multiple items in your catalog. Each request can support up to 50 items. +Use this endpoint to create multiple items in your catalog. Each request can support up to 50 items. This endpoint is asynchronous. {% alert important %} Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. @@ -27,74 +27,92 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints. -## Request body +## Path parameters -``` -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -``` - -```json -{ - "items": [ (max of 50 items) - { - "id": (required, item id), - "count": (required, item count), - }, - { - "id": (required, item id), - "count": (required, item count), - }, - { - "id": (required, item id), - "count": (required, item count), - } - ] -} -``` +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalog_name` | Required | String | Name of the catalog. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -### Request parameters +## Request parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `item_id` | Required | String | Item ID for a catalog item. | +| `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. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -## Example request +## Example Request + ``` -curl --location --request POST 'https://rest.iad-01.braze.com/catalogs/catalog_name/items' \ +curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ - "items": [ - { - "id": "item_0", - "count": 1, - }, - { - "id": "item_1", - "count": 2, - }, - { - "id": "item_2", - "count": 3, - } - ] + "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" + }, + { + "id": "restaurant2", + "Name": "Restaurant2", + "City": "New York", + "Cuisine": "American", + "Rating": 10, + "Loyalty_Program": true, + "Created_At": "2022-11-02T09:03:19.967+00:00" + }, + { + "id": "restaurant3", + "Name": "Restaurant3", + "City": "New York", + "Cuisine": "American", + "Rating": 3, + "Loyalty_Program": false, + "Created_At": "2022-11-03T09:03:19.967+00:00" + } + ] +}' +``` + +## Response + +There are three status code responses for this endpoint: `202`, `400`, and `404`. + +### Example success response + +The status code `202` could return the following response body. + +```json +{ + "message": "success" } ``` -## Example error response +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ { - "id": "catalog-not-found", - "message": "Could not find catalog", - "parameters": ["catalog_name"], - "parameter_values": ["catalog_name"] + "id": "fields-do-not-match", + "message": "Fields do not match with fields on the catalog", + "parameters": [ + "id" + ], + "parameter_values": [ + "restaurant2" + ] } - ] + ], + "message": "Invalid Request" } ``` @@ -105,12 +123,14 @@ The following table lists possible returned errors and their associated troubles | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | +| `item-array-invalid` | `items` must be an array of objects. | +| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. | | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. | | `ids-too-large` | Item IDs can't be more than 250 characters. | | `ids-not-unique` | Item IDs must be unique in the request. | +| `ids-not-strings` | Item IDs must be of type string. | | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | | `items-too-large` | Item values can't exceed 5,000 characters. | -| `request-includes-too-many-items` | Your request has too many items. The maximum is 50. | | `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `fields-do-not-match` | Updated fields must match the fields in the catalog. | | `unable-to-coerce-value` | Item types can't be converted. | diff --git a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/delete_catalog_item.md b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/delete_catalog_item.md index e24ee0cd017..0b836364518 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/delete_catalog_item.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/delete_catalog_item.md @@ -12,7 +12,7 @@ description: "This article outlines details about the Delete Catalog Item Braze {% api %} # Delete a catalog item {% apimethod delete %} -/catalogs/catalog_name/items/item_id +/catalogs/{catalog_name}/items/{item_id} {% endapimethod %} Use this endpoint to delete an item in your catalog. @@ -27,49 +27,70 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints. -### Request Parameters +## Request parameters + +There is no request body for this endpoint. + +## Path parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the imported catalog.| -| `item_id` | Required | String | Item ID. | +| `catalog_name` | Required | String | Name of the catalog. | +| `item_id` | Required | String | The ID of the catalog item. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} ## Example request ``` -https://rest.iad-03.braze.com/catalogs/catalog_name/items/item_id +curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' ``` -## Example error response +## Response + +There are three status code responses for this endpoint: `202`, `400`, and `404`. + +### Example success response + +The status code `202` could return the following response body. + +```json +{ + "message": "success" +} +``` + +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ - { - "id": "catalog-not-found", - "message": "Could not find catalog", - "paramters": ["catalog_name"], - "parameter_values": ["catalog_name"] - }, { "id": "item-not-found", "message": "Could not find item", - "parameters": ["item_id"], - "parameter_values": ["item_id"] + "parameters": [ + "item_id" + ], + "parameter_values": [ + "restaurant34" + ] } - ] + ], + "message": "Invalid Request" } ``` ## Troubleshooting -The following table lists possible returned errors and their associated troubleshooting steps, if applicable. +The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | -| `item-not-found`| Check that the item to be deleted exists in your catalog. | +| `item-not-found` | Check that the item to be deleted exists in your catalog. | | `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support]({{site.baseurl}}/support_contact/). | {: .reset-td-br-1 .reset-td-br-2} diff --git a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_item_details.md b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_item_details.md index e49384ba9a4..cd3a09989b2 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_item_details.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_item_details.md @@ -12,7 +12,7 @@ description: "This article outlines details about the List Catalog Item Details {% api %} # List catalog item details {% apimethod get %} -/catalogs/catalog_name/items/item_id +/catalogs/{catalog_name}/items/{item_id} {% endapimethod %} Use this endpoint to return a catalog item and its content. @@ -27,31 +27,71 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints. -### Request Parameters +## Path parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the catalog.| -| `item_id ` | Required | String | The ID of the catalog item. | +| `catalog_name` | Required | String | Name of the catalog. | +| `item_id` | Required | String | The ID of the catalog item. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} +## Request parameters + +There is no request body for this endpoint. + ## Example request ``` -https://rest.iad-03.braze.com/catalogs/catalog_name/items/item_id +curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response +There are two status code responses for this endpoint: `200` and `404`. + +### Example success response + +The status code `200` could return the following response body. + +```json +{ + "items": [ + { + "id": "restaurant3", + "Name": "Restaurant1", + "City": "New York", + "Cuisine": "American", + "Rating": 5, + "Loyalty_Program": true, + "Open_Time": "2022-11-01T09:03:19.967Z" + } + ], + "message": "success" +} +``` + +### Example error response + +The status code `404` could return the following response. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. + ```json -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -"items": [ +{ + "errors": [ { - "id": "0", - "count": 5, + "id": "item-not-found", + "message": "Could not find item", + "parameters": [ + "item_id" + ], + "parameter_values": [ + "restaurant34" + ] } -] + ], + "message": "Invalid Request" +} ``` ## Troubleshooting diff --git a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk.md b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk.md index 67289ba7e42..9adaccc0293 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk.md @@ -12,7 +12,7 @@ description: "This article outlines details about the List Multiple Catalog Item {% api %} # List multiple catalog item details {% apimethod get %} -/catalogs/catalog_name/items +/catalogs/{catalog_name}/items {% endapimethod %} Use this endpoint to return multiple catalog items and their content. @@ -27,49 +27,120 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints. -### Request Parameters +## Path parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the imported catalog.| -| `cursor` | Optional | String | Determines the pagination of the catalog items. | +| `catalog_name` | Required | String | Name of the catalog. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -## Example request +## Query parameters + +Note 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. + +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `cursor` | Optional | String | Determines the pagination of the catalog items. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} + +## Request parameters + +There is no request body for this endpoint. + +## Example requests + +### Without cursor + ``` -https://rest.iad-03.braze.com/catalogs/catalog_name/items +curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' ``` -## Example response +### With cursor -Note 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. +``` +curl --location --request GET 'https://rest.iad-03.braze.com/catalogs/restaurants/items?cursor=c2tpcDow' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' +``` -```json -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY +## Response + +There are three status code responses for this endpoint: `200`, `400`, and `404`. + +### Example success response + +The status code `200` could return the following response header and body. + +{% alert 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. +{% endalert %} + +``` Link: ; rel="prev",; rel="next" +``` + +```json +{ + "items": [ + { + "id": "restaurant1", + "Name": "Restaurant1", + "City": "New York", + "Cuisine": "American", + "Rating": 5, + "Loyalty_Program": true, + "Open_Time": "2022-11-02T09:03:19.967Z" + }, + { + "id": "restaurant2", + "Name": "Restaurant2", + "City": "New York", + "Cuisine": "American", + "Rating": 10, + "Loyalty_Program": true, + "Open_Time": "2022-11-02T09:03:19.967Z" + }, + { + "id": "restaurant3", + "Name": "Restaurant3", + "City": "New York", + "Cuisine": "American", + "Rating": 5, + "Loyalty_Program": false, + "Open_Time": "2022-11-02T09:03:19.967Z" + } + ], + "message": "success" +} +``` + +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. + +```json { - "items": [ - { - "id": "0", - "count": 1, - }, - { - "id": "1", - "count": 2, - }, - { - "id": "2", - "count": 3, - } - // ... max of 50 items - ] + "errors": [ + { + "id": "invalid-cursor", + "message": "'cursor' is not valid", + "parameters": [ + "cursor" + ], + "parameter_values": [ + "bad-cursor" + ] + } + ], + "message": "Invalid Request" } ``` ## Troubleshooting -The following table lists possible returned errors and their associated troubleshooting steps, if applicable. +The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | diff --git a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/patch_catalog_item.md b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/patch_catalog_item.md index 75839c2f4db..56d66a291fc 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/patch_catalog_item.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/patch_catalog_item.md @@ -12,7 +12,7 @@ description: "This article outlines details about the Edit Catalog Item Braze en {% api %} # Edit catalog item {% apimethod patch %} -/catalogs/catalog_name/items/item_id +/catalogs/{catalog_name}/items/{item_id} {% endapimethod %} Use this endpoint to edit an item in your catalog. @@ -23,79 +23,75 @@ Support for this endpoint is currently in early access. Contact your Braze accou If you'd like to share your feedback on this endpoint or make a request, contact the Braze Catalogs team at [catalogs-product@braze.com](mailto:catalogs-product@braze.com) -## Rate limit +## Rate Limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints. -## Request body -``` -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -``` +## Path parameters -```json -{ - "items": [ (max of 50 items) - { - "id": (required, item id) - "count": (required, item count) - }, - ] -} -``` +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalog_name` | Required | String | Name of the catalog. | +| `item_id` | Required | String | The ID of the catalog item. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -### Request parameters +## Request parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the catalog.| -| `item_id ` | Required | String | Item ID for a catalog item. | +| `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog except for the `id` field. Only one item object is allowed per request. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} ## Example request + ``` -curl --location --request PATCH 'https://rest.iad-01.braze.com/catalogs/my_catalog/items/my_item' \ +curl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ --header 'Content-Type: application/json' \ ---header 'Authorization: Bearer YOUR-API-KEY-HERE' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ - "items": [ - { - "count": "item_count" - }, - ] -} + "items": [ + { + "Name": "Restaurant", + "Loyalty_Program": false, + "Open_Time": "2021-09-03T09:03:19.967+00:00" + } + ] +}' ``` -## Example response +## Response + +There are three status code responses for this endpoint: `200`, `400`, and `404`. + +### Example success response + +The status code `200` could return the following response body. + ```json { - "items": [ - { - "id": "item_0", - "count": 5, - } - ] + "message": "success" } ``` -## Example error response +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ - { - "id": "ids-too-large", - "message": "Item ids can not be larger than 250 characters", - "parameters": ["id"], - "parameter_values": ["item_id"] - }, { "id": "invalid-fields", "message": "Some of the fields given do not exist in the catalog", - "parameters": ["id"], - "parameter_values": ["item_id"] + "parameters": [ + "id" + ], + "parameter_values": [ + "restaurant1" + ] } - ] + ], + "message": "Invalid Request" } ``` @@ -107,14 +103,15 @@ The following table lists possible returned errors and their associated troubles | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | | `item-not-found` | Check that the item is in the catalog. | -| `request-includes-too-many-items` | You can only edit one item in your catalog per request. | +| `item-array-invalid` | `items` must be an array of objects. | +| `request-includes-too-many-items` | You can only edit one catalog item per request. | | `id-in-body` | An item ID already exists in the catalog. | | `invalid-ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | | `ids-too-large` | Character limit for each item ID is 250 characters. | -| `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `items-too-large` | Character limit for each item is 5,000 characters. | -| `filtered-set-field-too-long` | The field value is being used in a filtered set that exceeds the character limit for an item. | +| `invalid-fields` | Confirm that the fields in the request exist in the catalog. | | `unable-to-coerce-value` | Item types can't be converted. | +| `filtered-set-field-too-long` | The field value is being used in a filtered set that exceeds the character limit for an item. | | `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support]({{site.baseurl}}/support_contact/). | {: .reset-td-br-1 .reset-td-br-2} diff --git a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/post_create_catalog_item.md b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/post_create_catalog_item.md index dd8533a2de9..9328be0b5f1 100644 --- a/_docs/_api/endpoints/catalogs/catalog_items/synchronous/post_create_catalog_item.md +++ b/_docs/_api/endpoints/catalogs/catalog_items/synchronous/post_create_catalog_item.md @@ -12,7 +12,7 @@ description: "This article outlines details about the Create Catalog Item Braze {% api %} # Create a catalog item {% apimethod post %} -/catalogs/catalog_name/items/item_id +/catalogs/{catalog_name}/items/{item_id} {% endapimethod %} Use this endpoint to create an item in your catalog. @@ -27,56 +27,74 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog item endpoints. -## Request body -``` -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -``` +## Path parameters -```json -{ - "items": [ (max of 1 item) - { - "count": (required, item count) - }, - ] -} -``` +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalog_name` | Required | String | Name of the catalog. | +| `item_id` | Required | String | The ID of the catalog item. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -### Request parameters +## Request parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the catalog.| -| `item_id` | Required | String | The item ID of the catalog item. | +| `items` | Required | Array | An array that contains item objects. The item objects should contain all of the fields in the catalog except for the `id` field. Only one item object is allowed per request. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -## Example response +## Example Request + +``` +curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' \ +--data-raw '{ + "items": [ + { + "Name": "Restaurant1", + "City": "New York", + "Cuisine": "American", + "Rating": 5, + "Loyalty_Program": true, + "Created_At": "2022-11-01T09:03:19.967+00:00" + } + ] +}' +``` + +## Response + +There are three status code responses for this endpoint: `201`, `400`, and `404`. + +### Example success response + +The status code `201` could return the following response body. ```json { - "items": [ - { - "count": 5, - } - ] + "message": "success" } ``` -## Example error response +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { "errors": [ { - "id": "catalog-not-found", - "message": "Could not find catalog" - }, - { - "id": "item-already-exists", - "message": "The item already exists" + "id": "fields-do-not-match", + "message": "Fields do not match with fields on the catalog", + "parameters": [ + "id" + ], + "parameter_values": [ + "restaurant2" + ] } - ] + ], + "message": "Invalid Request" } ``` @@ -87,6 +105,7 @@ The following table lists possible returned errors and their associated troubles | Error | Troubleshooting | | --- | --- | | `catalog-not-found` | Check that the catalog name is valid. | +| `item-array-invalid` | `items` must be an array of objects. | | `request-includes-too-many-items` | You can only create one catalog item per request. | | `id-in-body` | Remove any item IDs in the request body. | | `invalid-ids` | Supported characters for item ID names are letters, numbers, hyphens, and underscores. | diff --git a/_docs/_api/endpoints/catalogs/catalogs.md b/_docs/_api/endpoints/catalogs/catalog_management.md similarity index 64% rename from _docs/_api/endpoints/catalogs/catalogs.md rename to _docs/_api/endpoints/catalogs/catalog_management.md index 1a238fa2bcc..19d24bfde8c 100644 --- a/_docs/_api/endpoints/catalogs/catalogs.md +++ b/_docs/_api/endpoints/catalogs/catalog_management.md @@ -1,5 +1,5 @@ --- -nav_title: Catalogs +nav_title: Catalog Management config_only: true noindex: true page_order: 1 diff --git a/_docs/_api/endpoints/catalogs/catalogs/synchronous.md b/_docs/_api/endpoints/catalogs/catalog_management/synchronous.md similarity index 100% rename from _docs/_api/endpoints/catalogs/catalogs/synchronous.md rename to _docs/_api/endpoints/catalogs/catalog_management/synchronous.md diff --git a/_docs/_api/endpoints/catalogs/catalogs/synchronous/delete_catalog.md b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/delete_catalog.md similarity index 58% rename from _docs/_api/endpoints/catalogs/catalogs/synchronous/delete_catalog.md rename to _docs/_api/endpoints/catalogs/catalog_management/synchronous/delete_catalog.md index 9afa11c2f5b..5ce36214614 100644 --- a/_docs/_api/endpoints/catalogs/catalogs/synchronous/delete_catalog.md +++ b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/delete_catalog.md @@ -12,7 +12,7 @@ description: "This article outlines details about the Delete Catalog Braze endpo {% api %} # Delete catalog {% apimethod delete %} -/catalogs/catalog_name +/catalogs/{catalog_name} {% endapimethod %} Use this endpoint to delete a catalog. @@ -27,20 +27,42 @@ If you'd like to share your feedback on this endpoint or make a request, contact This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints. -### Request parameters +## Path parameters | Parameter | Required | Data Type | Description | |---|---|---|---| -| `catalog_name` | Required | String | Name of the catalog.| +| `catalog_name` | Required | String | Name of the catalog. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} +## Request parameters + +There is no request body for this endpoint. + ## Example request ``` -https://rest.iad-03.braze.com/catalogs/catalog_name +curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' \ +``` + +## Response + +There are two status code responses for this endpoint: `200` and `404`. + +### Example success response + +The status code `200` could return the following response body. + +```json +{ + "message": "success" +} ``` -## Example error response +### Example error response + +The status code `404` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. ```json { @@ -48,16 +70,21 @@ https://rest.iad-03.braze.com/catalogs/catalog_name { "id": "catalog-not-found", "message": "Could not find catalog", - "parameters": ["catalog_name"], - "parameter_values": ["catalog_name"] + "parameters": [ + "catalog_name" + ], + "parameter_values": [ + "restaurants" + ] } - ] + ], + "message": "Invalid Request" } ``` -## Troubleshooting +## Troubleshooting -The following table lists possible returned errors and their associated troubleshooting steps, if applicable. +The following table lists possible returned errors and their associated troubleshooting steps. | Error | Troubleshooting | | --- | --- | diff --git a/_docs/_api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs.md b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs.md new file mode 100644 index 00000000000..e443c6fdf8f --- /dev/null +++ b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs.md @@ -0,0 +1,124 @@ +--- +nav_title: "GET: List Catalogs" +article_title: "GET: List Catalogs" +search_tag: Endpoint +page_order: 2 + +layout: api_page +page_type: reference +description: "This article outlines details about the List Catalogs Braze endpoint." + +--- +{% api %} +# List catalogs in app group +{% apimethod get %} +/catalogs +{% endapimethod %} + +Use this endpoint to return a list of catalogs in an app group. + +{% alert important %} +Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. +{% endalert %} + +If you'd like to share your feedback on this endpoint or make a request, contact the Braze Catalogs team at [catalogs-product@braze.com](mailto:catalogs-product@braze.com) + +## Rate limit + +This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints. + +## Path parameters + +There are no path parameters for this endpoint. + +## Request parameters + +There is no request body for this endpoint. + +### Example request + +``` +curl --location --request GET 'https://rest.iad-03.braze.com/catalogs' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' +``` + +## Response + +### Example success response + +The status code `200` could return the following response body. + +```json +{ + "catalogs": [ + { + "description": "My Restaurants", + "fields": [ + { + "name": "id", + "type": "string" + }, + { + "name": "Name", + "type": "string" + }, + { + "name": "City", + "type": "string" + }, + { + "name": "Cuisine", + "type": "string" + }, + { + "name": "Rating", + "type": "number" + }, + { + "name": "Loyalty_Program", + "type": "boolean" + }, + { + "name": "Created_At", + "type": "time" + } + ], + "name": "restaurants", + "num_items": 10, + "updated_at": "2022-11-02T20:04:06.879+00:00" + }, + { + "description": "My Catalog", + "fields": [ + { + "name": "id", + "type": "string" + }, + { + "name": "string_field", + "type": "string" + }, + { + "name": "number_field", + "type": "number" + }, + { + "name": "boolean_field", + "type": "boolean" + }, + { + "name": "time_field", + "type": "time" + }, + ], + "name": "my_catalog", + "num_items": 3, + "updated_at": "2022-11-02T09:03:19.967+00:00" + }, + ], + "message": "success" +} +``` + +{% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog.md b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog.md new file mode 100644 index 00000000000..569578a3bf2 --- /dev/null +++ b/_docs/_api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog.md @@ -0,0 +1,188 @@ +--- +nav_title: "POST: Create Catalog" +article_title: "POST: Create Catalog" +search_tag: Endpoint +page_order: 3 + +layout: api_page +page_type: reference +description: "This article outlines details about the Create Catalog Braze endpoint." + +--- +{% api %} +# Create catalog +{% apimethod post %} +/catalogs +{% endapimethod %} + +Use this endpoint to create a catalog. + +{% alert important %} +Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. +{% endalert %} + +If you'd like to share your feedback on this endpoint or make a request, contact the Braze Catalogs team at [catalogs-product@braze.com](mailto:catalogs-product@braze.com) + +## Rate limit + +This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints. + +## Request parameters + +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `catalogs` | Required | Array | An array that contains catalog objects. Only one catalog object is allowed for this request. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} + +### Catalog object parameters + +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `name` | Required | String | The name of the catalog that you want to create. | +| `description` | Required | String | The description of the catalog that you want to create. | +| `fields` | Required | Array | An array of objects where the object contains keys `name` and `type`. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} + +## Example Request + +``` +curl --location --request POST 'https://rest.iad-03.braze.com/catalogs' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer YOUR-REST-API-KEY' \ +--data-raw '{ + "catalogs": [ + { + "name": "restaurants", + "description": "My Restaurants", + "fields": [ + { + "name": "id", + "type": "string" + }, + { + "name": "Name", + "type": "string" + }, + { + "name": "City", + "type": "string" + }, + { + "name": "Cuisine", + "type": "string" + }, + { + "name": "Rating", + "type": "number" + }, + { + "name": "Loyalty_Program", + "type": "boolean" + }, + { + "name": "Created_At", + "type": "time" + } + ] + } + ] +}' +``` + +## Response + +There are two status code responses for this endpoint: `201` and `400`. + +### Example success response + +The status code `201` could return the following response body. + +```json +{ + "catalogs": [ + { + "description": "My Restaurants", + "fields": [ + { + "name": "id", + "type": "string" + }, + { + "name": "Name", + "type": "string" + }, + { + "name": "City", + "type": "string" + }, + { + "name": "Cuisine", + "type": "string" + }, + { + "name": "Rating", + "type": "number" + }, + { + "name": "Loyalty_Program", + "type": "boolean" + }, + { + "name": "Created_At", + "type": "time" + } + ], + "name": "restaurants", + "num_items": 0, + "updated_at": "2022-11-02T20:04:06.879+00:00" + } + ], + "message": "success" +} +``` + +### Example error response + +The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. + +```json +{ + "errors": [ + { + "id": "catalog-name-already-exists", + "message": "A catalog with that name already exists", + "parameters": [ + "name" + ], + "parameter_values": [ + "restaurants" + ] + } + ], + "message": "Invalid Request" +} +``` + +## Troubleshooting + +The following table lists possible returned errors and their associated troubleshooting steps. + +| Error | Troubleshooting | +| --- | --- | +| `catalog-array-invalid` | `catalogs` must be an array of objects. | +| `too-many-catalog-atoms` | You can only create one catalog per request. | +| `invalid_catalog_name` | Catalog name can only include letters, numbers, hyphens, and underscores. | +| `catalog-name-too-large` | Character limit for a catalog name is 250. | +| `catalog-name-already-exists` | Catalog with that name already exists. | +| `id-not-first-column` | The `id` must be the first field in the array. Check that the type is a string. | +| `invalid-fields` | `fields` is not formatted correctly. | +| `too-many-fields` | Number of fields limit is 30. | +| `invalid-field-names` | Fields can only include letters, numbers, hyphens, and underscores. | +| `invalid-field-types` | Make sure the field types are valid. | +| `field-names-too-large` | Character limit for a field name is 250. | +| `field-names-not-unique` | The same field name is referenced twice. | +| `reached-company-catalogs-limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. | +| `description-too-long` | Character limit for description is 250. | +{: .reset-td-br-1 .reset-td-br-2} + +{% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs.md b/_docs/_api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs.md deleted file mode 100644 index a7bb2d9498c..00000000000 --- a/_docs/_api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -nav_title: "GET: List Catalogs" -article_title: "GET: List Catalogs" -search_tag: Endpoint -page_order: 2 - -layout: api_page -page_type: reference -description: "This article outlines details about the List Catalogs Braze endpoint." - ---- -{% api %} -# List catalogs in app group -{% apimethod get %} -/catalogs -{% endapimethod %} - -Use this endpoint to return a list of catalogs in an app group. - -{% alert important %} -Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. -{% endalert %} - -If you'd like to share your feedback on this endpoint or make a request, contact the Braze Catalogs team at [catalogs-product@braze.com](mailto:catalogs-product@braze.com) - -## Rate limit - -This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints. - -## Example request - -``` -https://rest.iad-03.braze.com/catalogs -``` - -## Response - -```json -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -{ - "catalogs": [ - { - "description": "this is catalog 1", - "fields": [ - { - "name": "id", - "type": "string" - }, - { - "name": "rating", - "type": "number" - } - ], - "name": "catalog_1", - "num_items": 5, - "updated_at": "2022-09-27T15:49:18.818+00:00" - }, - { - "description": "this is catalog_2", - "fields": [ - { - "name": "id", - "type": "string" - }, - { - "name": "column_1", - "type": "string" - }, - { - "name": "column_2", - "type": "number" - }, - { - "name": "column_3", - "type": "boolean" - }, - { - "name": "column_4", - "type": "time" - }, - ], - "name": "catalog_2", - "num_items": 10, - "updated_at": "2022-08-31T20:22:56.127+00:00" - } - ] -} -``` - -{% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/catalogs/catalogs/synchronous/post_create_catalog.md b/_docs/_api/endpoints/catalogs/catalogs/synchronous/post_create_catalog.md deleted file mode 100644 index 545387e7056..00000000000 --- a/_docs/_api/endpoints/catalogs/catalogs/synchronous/post_create_catalog.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -nav_title: "POST: Create Catalog" -article_title: "POST: Create Catalog" -search_tag: Endpoint -page_order: 3 - -layout: api_page -page_type: reference -description: "This article outlines details about the Create Catalog Braze endpoint." - ---- -{% api %} -# Create catalog -{% apimethod post %} -/catalogs -{% endapimethod %} - -Use this endpoint to create a catalog. - -{% alert important %} -Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access. -{% endalert %} - -If you'd like to share your feedback on this endpoint or make a request, contact the Braze Catalogs team at [catalogs-product@braze.com](mailto:catalogs-product@braze.com) - -## Rate limit - -This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints. - -## Request body - -``` -Content-Type: application/json -Authorization: Bearer YOUR-REST-API-KEY -``` - -```json -{ - "catalogs": [ (max of 1 item) - { - "name": (required, string), - "description": (required, string), - "fields": [ - { - "name": (required, string), - "type": (required, string) - }, - { - "name": (required, string), - "type": (required, string) - } - ] - } - ] -} -``` - -### Request parameters - -| Parameter | Required | Data Type | Description | -|---|---|---|---| -| `name` | Required | String | Name of the imported catalog.| -| `description` | Required | String | Description for the catalog. | -| `fields` | Required | Array of strings | Catalog items to create. | -{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} - -### Example request - -```json -curl --location --request POST 'https://rest.iad-01.braze.com/catalogs' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer YOUR-REST-API-KEY' \ ---data-raw '{ - "catalogs": [ - { - "name": "catalog_1", - "description": "this is catalog_1", - "fields": [ - { - "name": "id", - "type": "string" - }, - { - "name": "count" - "type": "number" - } - ] - }, - ] -} -``` - -## Troubleshooting - -The following table lists possible returned errors and their associated troubleshooting steps. - -| Error | Troubleshooting | -| --- | --- | -| `too-many-catalog-atoms` | Only 1 catalog is allowed per request. | -| `invalid_catalog_name` | Catalog name can only include letters, numbers, hyphens, and underscores. | -| `catalog-name-too-large` | Character limit for a catalog name is 250. | -| `catalog-name-already-exists` | Catalog with that name already exists. | -| `id-not-first-column` | The ID must be the first field in the array. Check that the type is a string. | -| `invalid-fields` | Field are not formatted correctly. | -| `too-many-fields` | Number of fields limit is 30. | -| `invalid-field-names` | Fields can only include letters, numbers, hyphens, and underscores. | -| `field-names-too-large` | Character limit for a field name is 250. | -| `field-names-not-unique` | Item types can't be converted. | -| `reached-company-catalogs-limit` | Maximum number of catalogs reached. Contact your Braze account manager for more information. | -| `description-too-long` | Character limit for description is 250. | -| `arbitrary-error` | An arbitrary error occurred. Please try again or contact [Support]({{site.baseurl}}/support_contact/). | -{: .reset-td-br-1 .reset-td-br-2} - -{% endapi %} \ No newline at end of file diff --git a/_docs/_api/home.md b/_docs/_api/home.md index c875f906ec5..f9eff846adb 100644 --- a/_docs/_api/home.md +++ b/_docs/_api/home.md @@ -352,15 +352,15 @@ glossaries: description: Create multiple items in your catalog. tags: - Catalogs - - name: /catalogs/catalog_name + - name: /catalogs/catalog_name description: Delete a catalog. tags: - Catalogs - - name: /catalogs/ + - name: /catalogs description: Create a catalog. tags: - Catalogs - - name: /catalogs/ + - name: /catalogs description: List the catalogs in an app group. tags: - Catalogs diff --git a/_docs/_user_guide/personalization_and_dynamic_content/catalogs/catalog.md b/_docs/_user_guide/personalization_and_dynamic_content/catalogs/catalog.md index 5d044215694..c8e84bbc5cc 100644 --- a/_docs/_user_guide/personalization_and_dynamic_content/catalogs/catalog.md +++ b/_docs/_user_guide/personalization_and_dynamic_content/catalogs/catalog.md @@ -160,9 +160,9 @@ You can leverage the [Catalogs Endpoints]({{site.baseurl}}/api/endpoints/catalog ### Managing catalogs -You can create a catalog using the [Create Catalogs]({{site.baseurl}}/api/endpoints/catalogs/catalogs/synchronous/post_create_catalog/) endpoint. +You can create a catalog using the [Create Catalogs]({{site.baseurl}}/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog/) endpoint. -As you build more catalogs, you can also use the [List Catalogs]({{site.baseurl}}/api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs/) endpoint to return a list of the catalogs in an app group. +As you build more catalogs, you can also use the [List Catalogs]({{site.baseurl}}/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs/) endpoint to return a list of the catalogs in an app group. ### Managing catalog items