Patch format and delivery

You can deliver patches to Bloomreach in several formats, depending on data size and integration requirements. Note that these only modify records via the Update Records job.

Direct JSON in request body

Format your patch as a JSON array of operations. Each operation is an object in the array. When delivering data in request body, Bloomreach supports gzip Content-Encoding. Specify the HTTP Header "Content-Encoding: gzip". You can compress and send 5 MB of compressed content. This functionality works for both Direct JSON and JSONLines.

[
  {
    "op": "add",
    "path": "/product-123",
    "value": { ... }
  },
  {
    "op": "upsert",
    "path": "/product-456/fields/price",
    "value": 29.99
  }
]

Use HTTP header: Content-Type: application/json-patch+json

Payload limit: approximately 5 MB.

Direct JSONLines in request body

Format your patch with one operation per line. Each line contains a complete JSON object.

{"op":"add","path":"/product-123","value":{...}}
{"op":"upsert","path":"/product-456/fields/price","value":29.99}

Use HTTP header: Content-Type: application/json-patch+jsonlines

Payload limit: approximately 100 MB.

Large patch uploads

File upload with reference

For larger patches, upload files to Bloomreach-managed storage first using the "get upload urls" mechanism. Then, reference these uploaded files in your patch submission.

Files must be in JSONLines format. Bloomreach accepts GZIP compression and if the file is compressed, the file name must have the .gz extension. Bloomreach automatically decompresses compressed files (.gz extension).

File size limit: up to 100 GB per file.

Works best for:

Large daily full feeds.
High-frequency updates exceeding request body limits.
Batch processing workflows.

Step 1: Request upload URLs

Make a "get upload urls" API call to get one or more HTTPS URLs to upload patch content to.

curl -X POST ".../workspace_id/upload-urls" \
  'api-key:api-secret' \
  -H 'Content-Type: application/json' \
  -d '{"file_paths": 
    ["file1.json.gz"]}'

**Returns:: A list of URLs for each file path specified.

Step 2: Upload data to URLs

Upload data directly to the URLs for each file path using HTTP PUT.

curl -X PUT "URL_FROM_STEP_1_RESPONSE" --data-binary @file1.json.gz

Note: This can be compressed or uncompressed (use .gz extension across all steps if compressed).

Step 3: Reference in update

Reference the file paths that have the uploaded patch data directly in the "update_records" API call.

curl -X POST ".../records/update_mode=full \
  'api-key:api-secret' \
  -H 'Content-Type: application/json' \
  -d '{"file_paths": 
    ["file1.json.gz"]}'

Result: The system will use the contents of the file as the patch.

Patch processing and jobs

Bloomreach uses a micro-batching approach, not real-time streaming. When you submit a patch, Bloomreach queues it for processing and returns immediately with a job identifier. The system then processes patches asynchronously in batches.

You can query the job identifier to track progress and check for success or errors. This batching approach provides better throughput and reliability than processing individual operations as they arrive.