Braze Catalogs > Catalog Management > Synchronous API
The Catalogs > Catalog Management > Synchronous API from Braze — 2 operation(s) for catalogs > catalog management > synchronous.
OpenAPI Specification
openapi: 3.0.0
info:
title: Braze Catalogs > Catalog Management > Synchronous API
description: 'The Braze and Radar integration allows you to access sophisticated location-based campaign triggers and user profile enrichment with rich, first-party location data. When Radar geofence or trip tracking events are generated, custom events and user attributes are sent to Braze in real-time. These events and attributes can then be used to trigger location-based campaigns, power last-mile pickup and delivery operations, monitor fleet and shipping logistics, or build user segments based on location patterns. '
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
security:
- BearerAuth: []
tags:
- name: Catalogs > Catalog Management > Synchronous
paths:
/catalogs/{catalog_name}:
delete:
tags:
- Catalogs > Catalog Management > Synchronous
summary: Delete Catalog
description: "> Use this endpoint to delete a catalog. \n \n\nTo use this endpoint, youll need to generate an API key with the `catalogs.delete` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 5 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\nTo use this endpoint, youll need to generate an API key with the `catalogs.get` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 5 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\nTo use this endpoint, youll need to generate an API key with the `catalogs.create` permission.\n\n## Rate limit\n\nThis endpoint has a shared rate limit of 5 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'
components:
responses:
Forbidden:
description: 403 Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: 401 Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: 429 Rate Limited
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: 404 Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: 400 Bad Request
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