--- openapi: 3.0.3 info: title: Braze REST API – Create catalog description: 'Use this endpoint to create a catalog. ' version: 1.0.0 contact: name: Braze Support url: https://www.braze.com/docs/braze_support/ license: name: Braze Documentation url: https://www.braze.com/docs/api/home/ servers: - url: https://rest.iad-01.braze.com description: US-01 - url: https://rest.iad-02.braze.com description: US-02 - url: https://rest.iad-03.braze.com description: US-03 - url: https://rest.iad-04.braze.com description: US-04 - url: https://rest.iad-05.braze.com description: US-05 - url: https://rest.iad-06.braze.com description: US-06 - url: https://rest.iad-07.braze.com description: US-07 - url: https://rest.iad-08.braze.com description: US-08 - url: https://rest.us-10.braze.com description: US-10 - url: https://rest.fra-01.braze.eu description: EU-01 - url: https://rest.fra-02.braze.eu description: EU-02 - url: https://rest.au-01.braze.com description: AU-01 - url: https://rest.id-01.braze.com description: ID-01 - url: https://rest.jp-01.braze.com description: JP-01 - url: https://rest.kr-01.braze.com description: KR-01 security: - BearerAuth: [] paths: "/catalogs": post: summary: Create catalog description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `catalogs.create` permission. ## Rate limit This endpoint has a shared rate limit of 50 requests per minute between all synchronous catalog endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | |---|---|---|---| | `catalogs` | Required | Array | An array that contains catalog objects. Only one catalog object is allowed for this request. | ### Catalog object parameters The following table lists the request parameters for this endpoint. | 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`. | ## 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": "Location", "type": "geo" }, { "name": "Preferences", "type": "object" }, { "name": "Top_Dishes", "type": "array" }, { "name": "Created_At", "type": "time" } ] } ] }' ``` **Note:** The `geo` data type stores a geographic coordinate as an array formatted as `[longitude, latitude]`. For example, `[-73.988103, 40.779109]`. ## 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": "Location", "type": "object" }, { "name": "Top_Dishes", "type": "array" }, { "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. | | `catalog-name-already-exists` | Catalog with that name already exists. | | `catalog-name-too-large` | Character limit for a catalog name is 250. | | `description-too-long` | Character limit for description is 250. | | `field-names-not-unique` | The same field name is referenced twice. | | `field-names-too-large` | Character limit for a field name is 250. | | `id-not-first-column` | The `id` must be the first field in the array. Check that the type is a string. | | `invalid-catalog-name` | Catalog name can only include letters, numbers, hyphens, and underscores. | | `invalid-field-names` | Fields can only include letters, numbers, hyphens, and underscores. | | `invalid-field-types` | Make sure the field types are valid. | | `invalid-fields` | `fields` is not formatted correctly. | | `too-many-catalog-atoms` | You can only create one catalog per request. | | `too-many-fields` | Number of fields limit is 500. | ## Response status codes The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it. | Status code | Meaning | Error message | How to resolve | | --- | --- | --- | --- | | `200 OK` | The request succeeded and the catalog was created. | `success` | No action needed. | | `400 Bad Request` | The `name` is blank or contains unsupported characters. | `Catalog name can only include letters, numbers, hyphens, and underscores, and can not be blank` | Use a `name` with only letters, numbers, hyphens, and underscores. | | `400 Bad Request` | The `name` is longer than 250 characters. | `Invalid Request` | Shorten the catalog `name` to 250 characters or fewer. | | `400 Bad Request` | The `description` is longer than 250 characters. | `Description must be no more than 250 characters` | Shorten the `description` to 250 characters or fewer. | | `400 Bad Request` | The first field isn't the required `id` string field. | `Invalid Request` | Make the first field `{"name": "id", "type": "string"}`. | | `400 Bad Request` | One or more field names are blank or use unsupported characters. | `Field names can not be blank and can only include letters, numbers, hyphens, and underscores` | Use field names with only letters, numbers, hyphens, and underscores. | | `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). | | `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `catalogs.create` permission. | | `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). | | `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). | operationId: post_catalogs_post_create_catalog tags: - Catalogs responses: '200': description: The request succeeded and the catalog was created. content: application/json: schema: $ref: '#/components/schemas/CreateCatalogResponse' '400': description: |- Bad Request. Causes include: - `Catalog name can only include letters, numbers, hyphens, and underscores, and can not be blank` — The `name` is blank or contains unsupported characters. - `Invalid Request` — The `name` is longer than 250 characters. - `Description must be no more than 250 characters` — The `description` is longer than 250 characters. - `Invalid Request` — The first field isn't the required `id` string field. - `Field names can not be blank and can only include letters, numbers, hyphens, and underscores` — One or more field names are blank or use unsupported characters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The REST API key is missing, malformed, or sent to the wrong REST endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The REST API key doesn't have the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: You exceeded the rate limit for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '5XX': description: An unexpected error occurred on the Braze server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: required: true content: application/json: schema: type: object required: - catalogs properties: catalogs: type: array description: An array that contains catalog objects. Only one catalog object is allowed for this request. items: type: object required: - name - description - fields properties: name: type: string description: The name of the catalog that you want to create. description: type: string description: The description of the catalog that you want to create. fields: type: array description: 'An array of objects where the object contains keys `name` and `type`. The first field must be `{"name": "id", "type": "string"}`.' items: type: object required: - name - type properties: name: type: string description: The name of the field. type: type: string description: The data type of the field. components: schemas: CreateCatalogResponse: type: object properties: catalogs: type: array items: type: object properties: description: type: string fields: type: array items: type: object properties: name: type: string type: type: string name: type: string num_items: type: integer updated_at: type: string message: type: string ErrorResponse: type: object properties: errors: type: array items: type: object properties: id: type: string message: type: string parameters: type: array items: type: string parameter_values: type: array items: type: string message: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key