Skip to content

Create catalog

post

/catalogs

Use this endpoint to create a catalog.

See me in Postman

Rate limit

This endpoint has a shared rate limit of 5 requests per minute between all synchronous catalog endpoints, as documented in API rate limits.

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.

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.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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": "object"
        },
        {
          "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
  "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": "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 for more information about errors you may encounter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "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.
  Edit this page on GitHub
WAS THIS PAGE HELPFUL?
New Stuff!