---
updatedAt: 2026-06-15T13:08:00.000Z
agentTools:
  siteIndex: https://documentation.bloomreach.com/llms.txt
  projectIndex: https://documentation.bloomreach.com/discovery/llms.txt
---

# Upload image

This API allows you to upload an image for [Visual Search](https://documentation.bloomreach.com/discovery/docs/visual-search).

## Endpoints

* Production: `https://pathways.dxpapi.com/api/v2/widgets/visual/upload/{widget_id}`
* Staging: `https://pathways-staging.dxpapi.com/api/v2/widgets/visual/upload/{widget_id}`

## Response Example

> 🚧 The request payload should not exceed 2 MB.

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.

```json JSON
{
    "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"
        }
    }
}
```

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recommendations and Pathways API",
    "version": "2.0"
  },
  "paths": {
    "/visual/upload/{widget_id}": {
      "post": {
        "tags": [
          "Visual search"
        ],
        "summary": "Upload image",
        "operationId": "upload-api",
        "deprecated": false,
        "parameters": [
          {
            "$ref": "#/components/parameters/WidgetId"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "name": "auth_key",
            "in": "query",
            "description": "The unique key shared during the integration phase. This is used to authenticate your API call.\n",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "name": "Content-Disposition",
            "description": "This specifies the form field as \"image\" and the suggested filename of the image being uploaded.         \nExample syntax: `Content-Disposition: form-data; name=\"image\"; filename=\"filename.jpg\"`\n",
            "in": "header",
            "schema": {
              "type": "string",
              "default": "form-data; name=\"image\"; filename=\"filename.jpg\""
            },
            "required": true,
            "example": "form-data; name=\"image\"; filename=\"filename.jpg\""
          },
          {
            "name": "Content-Type",
            "description": "This header specifies the media type (image) and format. We accept all image formats - jpg, png, jpeg, webp.\nExample syntax: `Content-Type: image/jpeg`\n",
            "in": "header",
            "schema": {
              "type": "string",
              "default": "image/jpeg"
            },
            "required": true,
            "example": "image/jpeg"
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "WidgetId": {
        "name": "widget_id",
        "in": "path",
        "description": "The ID of the widget, which can be found in the [Widget Configurator](https://documentation.bloomreach.com/discovery/docs/widget-configurator) in the Dashboard.\n\nThe example value shown here, <i>1jwy7eg9</i>, is included for your convenience to send a request with <b>Try It</b>.\n",
        "schema": {
          "type": "string",
          "default": "1jwy7eg9"
        },
        "required": true,
        "example": "1jwy7eg9"
      },
      "AccountId": {
        "name": "account_id",
        "in": "query",
        "description": "Your site's numerical Bloomreach account ID.\n\nYour Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.\nThe example value shown here, <i>6276</i>, is included for your convenience to send a request with <b>Try It</b>.\n",
        "required": true,
        "example": 6276,
        "schema": {
          "type": "integer",
          "format": "int32",
          "default": 6276
        }
      },
      "DomainKey": {
        "name": "domain_key",
        "in": "query",
        "description": "Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests.\n\nThis parameter identifies the specific site version when one account ID hosts multiple site versions with unique characteristics, such as language versions.\nThe example value shown here, <i>bloomreach_devdocs</i>, is included for your convenience to send a request with <b>Try It</b>.\n",
        "required": true,
        "example": "bloomreach_devdocs",
        "schema": {
          "type": "string",
          "default": "bloomreach_devdocs"
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://pathways.dxpapi.com/api/v2/widgets"
    }
  ],
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "x-readme-fauxas": true
}
```