Upload API

This API allows you to upload the image for Visual Search.


Path Parameters

widget_idstringThe ID of the widget, which can be found in the Widget Configurator in the Dashboard.required

Query Parameters

account_idintegerYour site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.required
domain_keystringYour site domain's ID, which Bloomreach provides during initial scoping and integration. This ID is for the domain that you want to receive your Bloomreach API requests. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions.required


auth_keystringThe unique key shared during the integration phase. This is used to authenticate a merchant API call.required

Request Payload - Form Data

Content-DispositionstringThis specifies the form field as "image" and the suggested filename of the image being uploaded.

Example syntax: Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-TypestringThis header specifies media type (image) and format. We accept all image formats - jpg, png, jpeg, webp.

Example syntax: Content-Type: image/jpeg


The request payload should not exceed 2 MB.

Response Example

The response provides you with the image_id value.

image_id can be used to make multiple subsequent queries for widget responses (with different parameters/filters and objects) without the need to re-upload the image.

    "response": {
       "image_id": "3d4b4331763c31b39da02704d48e890f90c36ef6b4835eface4820a3e1127987"
    "metadata": {
        "widget": {
            "id": "79opvm5j",
            "name": "preview",
            "description": "preview",
            "type": "visual_search",
            "rid": "680d0382-7297-4db7-9df7-61522b4612c7"
        "query": {
            "image_id": "3d4b4331763c31b39da02704d48e890f90c36ef6b4835eface4820a3e1127987"

Click Try It! to start a request and see the response here!