Upload an asset to the media library

Use this endpoint to add an asset to the Braze media library using either an externally hosted URL (asset_url) or binary file data sent in the request body (asset_file). This endpoint supports images and ZIP files that contain images.

tip

You can also call this endpoint through the Braze MCP server using the create_media_library_asset function. This lets AI tools like Claude and Cursor upload assets to your media library through natural language prompts.

Prerequisites

To use this endpoint, you’ll need an API key with the media_library.create permission.

Rate limit

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

Request body

When you include asset_url, the endpoint downloads the file from the URL. When you include asset_file, the endpoint uses the binary data in the request body.

Example request body for asset_url:

1
2
3
4
{
  "asset_url": "https://cdn.example.com/assets/cat.jpg",
  "name": "Cat Graphic"
}

Example request body for asset_file:

1
2
3
4
{
  "asset_file": <BINARY FILE DATA>,
  "name": "Cat Graphic"
}

The request body includes the following parameters:

important

asset_url and asset_file are mutually exclusive, you must only include one of them in your API request.

Uploaded file names

This section explains how the endpoint assigns names to uploaded files based on whether you include the name parameter.

Single file uploads

ZIP file uploads

Example request

This section includes two example curl requests, one for adding an asset using a URL and another using binary file data.

This request shows an example of adding an asset to the media library using an asset_url.

1
2
3
4
curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_url": "https://cdn.example.com/assets/cat.jpg", "name": "Cat Graphic"}'

This request shows an example of adding an asset to the media library using an asset_file.

1
2
3
4
curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_file":<BINARY FILE DATA>, "name":"Cat Graphic"}'

Error responses

This section lists potential errors and their corresponding messages and descriptions.

Validation errors

Validation errors return a structure like this:

1
2
3
{
  "message": (String) Human-readable error description
}

This table lists possible validation errors.

Processing errors

Processing errors return a different response with error codes:

1
2
3
4
5
{
  "message": (String) Human-readable error description,
  "error_code": (String) error code,
  "meta": { }
}

This table lists possible processing errors.

Response

There are five status code responses for this endpoint: 200, 400, 403, 429, and 500.

The following JSON shows the expected shape of the response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{ 
    "new_assets": [
        {
            "name": (String) the name of the asset,
            "size": (Integer) the byte size of the asset,
            "url": (String) the URL to access the asset,
            "ext": (String) the file extension (e.g., "png", "jpg", "gif")
        }
    ],
    "errors": [
        {
            "name": (String) the name of the asset,
            "size": (Integer) the byte size of the asset,
            "ext": (String) the file extension (e.g., "png", "jpg", "gif"),
            "error": (String) the error that occurred
        }
    ],
    "dashboard_url": (String) the URL to view this asset in the Braze dashboard
}