Upload full feed

❗️

You may see an "Accept" header (Accept: application/json) in the request examples of some languages. Please omit that since it is just a quirk of the example module. Also, make sure to use the correct Content-Type header from here.

Using the PUT method, you can replace the catalog’s data entirely. We recommend sending your data through an SFTP file transfer when using PUT mode.

You don't need to update the entire catalog daily using PUT, and we recommend using PATCH mode if you need to make frequent updates. We recommend using PUT mode if you update a large part of your catalog data, but generally you should limit using PUT requests. In PUT mode, a configurable percentage of malformed products is allowed.

After formatting your data, you must deliver it to Bloomreach using one of two methods:

• Direct API payload: send your catalog data directly via an API payload
• SFTP file : send your catalog data via a file on SFTP

Before you begin

Before sending your Catalog data to Bloomreach via the Catalog Management API, ensure that you have the following:

• Formatted catalog data - Create your catalog data according to the Format your Data page.
• API key - You need an API key in the header for authentication. If you don't already have it, create and manage new keys following the API key management guide.
• Catalog names - Catalog names used in the Catalog Management API endpoints. Use the same value as your domain key in your search API requests.

Steps

1. If sending data through SFTP, upload your catalog data to your Bloomreach SFTP location.
2. Send the Upload full feed PUT API request.
3. Run an indexing job.

❗️

Warning

If there are any malformed records in your catalog data, the whole operation will be invalid and no changes will be applied.

Send Data as API payload

To send your catalog data directly via an API payload, you must convert all of the operations into a single JSON Patch, which is an array of catalog records. In your Catalog Data Management API request body, include the catalog records.

The max size of a single API payload is 5MB.

[{
  "op": "add",
  "path": "/products/pid-123",
  "value": {
    "attributes": {
      "title": "Example 123",
      "price": 100,
      "description": "Example product description here",
      "url": "http://www.example.com/example-product-url.html",
      "availability": true
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-456",
  "value": {
    "attributes": {
      "title": "Example 456",
      "tags": ["", ""]
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-789",
  "value": {
    "attributes": {
      "title": "Example 789",
      "category": "Seafood",
      "tags": ["", ""]
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-101112/attributes/availability",
  "value": false
}
]

[{
   "op":"add",
   "path":"/items/awesome_omelette_pdf",
   "value":{
      "attributes":{
         "title":"Awesome Omelette",
         "url":"https://www.homeoasis.com/pdf/awesome-omelette.pdf",   
  "medium_image_url":"https://www.homeoasis.com/images/recipe/201851/img1.jpg",
         "rating":4.7,
         "category":[
            "PDF",
            "Breakfast"
         ],
      },
      "@import":{
         "path":"/pdfs/awesome_omelette.pdf"
      }
   }
},
{ 
   "op":"add", 
   "path":"/items/awesome_omelette_video", 
   "value":{ 
      "attributes":{ 
         "title":"How to Make Our Awesome Omelette", 
         "url":"https://www.homeoasis.com/video/awesome-omelette-video.html", 
         "description":"Follow along our Awesome Omelette recipe with this companion video.", 
         "medium_image_url":"https://www.homeoasis.com/images/recipe/201851/img1.jpg", 
         "rating":4.7, 
         "video_id":HDRS2748, 
         "video_duration":5, 
         "category":[ 
            "Videos", 
            "Breakfast" 
         ], 
      }, 
   } 
}]

📘

Mandatory field for Autosuggestions

url field is mandatory for product and attribute suggestions to be returned in the Autosuggest API.

Sending up to 1 GB data (only Product) using JSON Lines

You can send more than 5 MB (and up to 1 GB) of data by formatting your JSON Patch as JSON Lines. For this, each valid JSON Patch operation object should be on a single line.

Here’s a sample request body in the JSON Lines format:

{"op":"add", "path":"/products/123", "value":{...}}
{"op":"add", "path":"/products/456", "value":{...}}
{"op":"add", "path":"/products/789", "value":{...}}
{"op":"add", "path":"/products/abc", "value":{...}}
{"op":"add", "path":"/products/def", "value":{...}}

curl --request PUT \
     --url https://api.connect.bloomreach.com/dataconnect/api/v1/accounts/6702/catalogs/catalog_name/products \
     --header 'Content-Type: application/json-patch+jsonlines' \
     --data '
     {"op":"add", "path":"/products/123", "value":{...}}
     {"op":"add", "path":"/products/456", "value":{...}}
     {"op":"add", "path":"/products/789", "value":{...}}
     {"op":"add", "path":"/products/abc", "value":{...}}
     {"op":"add", "path":"/products/def", "value":{...}}    
'

Additionally, you must use the following Content-Type header:

Content-Type: application/json-patch+jsonlines

You may gzip compress the request payload; however, the uncompressed payload may not be larger than 1GB. A gzip compressed request payload must also include the Content-Encoding: gzip HTTP header.

Good to Remember

• When the request is made via cURL, the data should be sent as binary (--data-binary) so that the newlines remain intact.

Send Data as a file through SFTP

📘

Note

If you are using our legacy FTP and SFTP server (ftp.bloomreach.com), upgrade to the latest SFTP service using the linked guide before July 20, 2025.

To send your catalog data via a file on SFTP, you must convert all of the patch operations into a file of JSONLines. Each line should only contain one patch operation. In your Catalog Data Management API request body, include the relative path to the file location.

Feed files may be sent uncompressed, or be compressed using gzip. The maximum size of a single API payload is 5MB.

In the request body, provide the paths to your catalog files as relative paths. For example, if your catalog files are in a folder named "content_en", then the request body should look like the following:

{"op": "add", "path": "/products/pid-123", "value": {...}} //First product record
{"op": "add", "path": "/products/pid-456", "value": {...}} //Second product record
{"op": "add", "path": "/products/pid-789", "value": {...}} //Third product record, etc.
…

{"op": "add", "path": "/items/item-123", "value": {...}} //First item record
{"op": "add", "path": "/items/item-456", "value": {...}} //Second item record
{"op": "add", "path": "/items/item-789", "value": {...}} //Third item record, etc.
…

[ 
  "<catalog-name>/<catalog1.jsonl>", 
  "content_en/20200410-090909-products2_staging.jsonl" 
]

📘

When to use SFTP transfer

Other than the case that you have already been using SFTP File Transfer in your organization's workflow and that it's convenient for you, there are other reasons why you can consider using it:

• If you want to send more than 1 GB data, which is not possible through a direct payload.
• If you're sending sensitive data, SFTP is a highly secure option.
• SFTP transfer lets you independently control when you want to send the data and when to ingest it (or even send it to an intermediary server).

SFTP Endpoints

• Production: sftp.connect.bloomreach.com (3.82.164.133, port 22)
• Staging: sftp-staging.connect.bloomreach.com (54.211.108.247, port 22)

Your SFTP command should look like the following:

sftp -i ~/path/to/private_key <username>@sftp-staging.connect.bloomreach.com

Provide Bloomreach with public keys that will need access to each environment. More than one can be provided for each environment, and we advise using different public keys for staging and production.

📘

SFTP tips

SFTP directory structure

Any catalog data files should be sent via the SFTP location provided in the SFTP Endpoints section. We suggest organizing catalogs into their own folders to help with debugging. For example, you could create a folder called <catalog_name> and then place files related to that catalog in this folder.

File naming

We suggest naming your catalog data files to include the catalog name, the type of modification (put/full, patch/delta) and a datetime version identifier. This will help with debugging. For example, if your catalog is named <catalog_name>, you could name your file 20200410-090909-<catalog_name>_full.jsonl

Storage length

Files sent to the Bloomreach SFTP are stored for 30 days. Files that are older than 30 days will be automatically deleted and cleared.

Job ID

The response contains a job ID that can be used to query for status.

Sample PUT request 

Parameters Overview