--- openapi: 3.0.3 info: title: Braze REST API – Create catalog description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) 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/). 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 operationId: post_catalogs_post_create_catalog requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCatalogRequest' examples: restaurants: summary: Create a restaurants catalog value: 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 responses: "201": description: The request succeeded and the catalog was created. No action needed. content: application/json: schema: $ref: '#/components/schemas/CreateCatalogResponse' examples: success: summary: Catalog created value: 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 "400": description: | Bad request. To resolve it: - **`catalogs-array-is-invalid`:** `catalogs` must be an array of objects. - **`catalog-name-already-exists`:** Catalog with that name already exists. - **`catalog-name-too-large`:** The `name` is longer than 250 characters. Character limit for a catalog name is 250. Shorten the catalog `name` to 250 characters or fewer. - **`description-too-long`:** The `description` is longer than 250 characters. Character limit for description is 250. Shorten the `description` to 250 characters or fewer. - **`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 first field isn't the required `id` string field. The `id` must be the first field in the array. Check that the type is a string. Make the first field `{"name": "id", "type": "string"}`. - **`invalid-catalog-name`:** The `name` is blank or contains unsupported characters. Catalog name can only include letters, numbers, hyphens, and underscores. Use a `name` with only letters, numbers, hyphens, and underscores. - **`invalid-field-names`:** One or more field names are blank or use unsupported characters. Fields can only include letters, numbers, hyphens, and underscores. Use field names with only 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. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: catalogs_array_is_invalid: summary: The catalogs array is invalid value: errors: - id: catalogs-array-is-invalid message: The catalogs array is invalid parameters: [] parameter_values: [] message: Invalid Request catalog_name_already_exists: summary: A catalog with that name already exists value: errors: - id: catalog-name-already-exists message: A catalog with that name already exists parameters: - name parameter_values: - restaurants message: Invalid Request catalog_name_too_large: summary: Catalog name longer than 250 characters value: errors: - id: catalog-name-too-large message: Catalog name can not be larger than 250 characters parameters: - name parameter_values: - "" message: Invalid Request description_too_long: summary: Description longer than 250 characters value: errors: - id: description-too-long message: Description must be no more than 250 characters parameters: - description parameter_values: - "" message: Invalid Request field_names_not_unique: summary: Field names aren't unique value: errors: - id: field-names-not-unique message: Fields are not unique parameters: - fields parameter_values: - City message: Invalid Request field_names_too_large: summary: Field name longer than 250 characters value: errors: - id: field-names-too-large message: Fields can not be larger than 250 characters parameters: - fields parameter_values: - "..." message: Invalid Request id_not_first_column: summary: The id isn't the first field value: errors: - id: id-not-first-column message: The id is not the first field in the array or type is not a string parameters: - fields parameter_values: [] message: Invalid Request invalid_catalog_name: summary: Invalid catalog name value: errors: - id: invalid-catalog-name message: Catalog name can only include letters, numbers, hyphens, and underscores, and can not be blank parameters: - name parameter_values: - my restaurants message: Invalid Request invalid_field_names: summary: Invalid field names value: errors: - id: invalid-field-names message: Field names can not be blank and can only include letters, numbers, hyphens, and underscores parameters: - fields parameter_values: - Created At message: Invalid Request invalid_field_types: summary: Invalid field types value: errors: - id: invalid-field-types message: Field types can not be invalid parameters: - fields parameter_values: - Rating message: Invalid Request invalid_fields: summary: The fields value isn't formatted correctly value: errors: - id: invalid-fields message: "'fields' value is not formatted correctly" parameters: - fields parameter_values: [] message: Invalid Request too_many_catalog_atoms: summary: More than one catalog value: errors: - id: too-many-catalog-atoms message: Only 1 catalog is allowed per request parameters: [] parameter_values: [] message: Invalid Request too_many_fields: summary: Too many fields value: errors: - id: too-many-fields message: Too many fields (maximum is 500) parameters: - fields parameter_values: [] message: Invalid Request "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `catalogs.create` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: over_rate_limit: summary: Over rate limit value: message: You have exceeded your limit of 50 requests per minute. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/. 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key description: | REST API keys are created in the Braze dashboard at **Settings → APIs and Identifiers → API Keys**. The key must include the `catalogs.create` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: CatalogField: title: Catalog field type: object required: - name - type properties: name: type: string maxLength: 250 pattern: '^[A-Za-z0-9_-]+$' description: The name of the field. example: id type: type: string description: | The data type of the field. The `geo` data type stores a geographic coordinate as an array formatted as `[longitude, latitude]`. For example, `[-73.988103, 40.779109]`. example: string NewCatalog: title: Catalog object type: object required: - name - description - fields properties: name: type: string maxLength: 250 pattern: '^[A-Za-z0-9_-]+$' description: The name of the catalog that you want to create. example: restaurants description: type: string maxLength: 250 description: The description of the catalog that you want to create. example: My Restaurants 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: $ref: '#/components/schemas/CatalogField' CreateCatalogRequest: title: Create catalog request type: object required: - catalogs properties: catalogs: type: array maxItems: 1 description: An array that contains catalog objects. Only one catalog object is allowed for this request. items: $ref: '#/components/schemas/NewCatalog' CreateCatalogResponse: title: Create catalog response type: object properties: catalogs: type: array items: title: Catalog type: object properties: description: type: string example: My Restaurants fields: type: array items: title: Catalog field type: object properties: name: type: string example: id type: type: string example: string name: type: string example: restaurants num_items: type: integer example: 0 updated_at: type: string example: "2022-11-02T20:04:06.879+00:00" message: type: string example: success ErrorResponse: title: Error type: object properties: errors: type: array items: title: Catalog error type: object properties: id: type: string example: catalog-name-already-exists message: type: string example: A catalog with that name already exists parameters: type: array items: type: string parameter_values: type: array items: type: string message: type: string