Navigation
🚨

Critical Security Migration

The luigisbox.com domain is compromised. Immediate action is required.

1. Update API Base URLs

Replace the base URL for all API requests (Search, Recommendations, Analytics):

https://live.luigisbox.com
➡️ https://live.luigisbox.tech

2. Replace Frontend Script

The .com script is no longer safe. Replace it with the secure version immediately:

[OLD - Delete from site]
<script async src="https://scripts.luigisbox.com/LBX-123.js"></script>
[NEW - Secure Version]
<script async src="https://scripts.luigisbox.tech/LBX-123.js"></script>

3. Update CSP & Firewalls

If you use a Content Security Policy, whitelist the new domain to prevent the browser from blocking the connection.

script-src https://scripts.luigisbox.tech;
connect-src https://live.luigisbox.tech;
⚠️
Emergency Action: If you cannot update the code right now, remove the existing Luigi's Box script until the migration is complete to prevent unauthorized code execution.
Support: support@luigisbox.net MODIFIED: 12/17/2025
API v1 API v2

Content Update (POST) v2

Add new objects or completely replace existing ones in your Luigi's Box search index using the v2 Content Update API endpoint.

Note

This endpoint requires HMAC authentication. Refer to the Authentication documentation for details.

Overview

This is the v2 version of the Content Update API endpoint. This endpoint is the primary method for adding new objects or completely replacing existing ones in your search index. You send an array of objects in a JSON payload, and Luigi's Box processes them in a batch.

!
Warning

This is a full replacement operation. When you update an existing object, any fields you omit from the request will be removed from the index. If you only need to update specific fields, it is more efficient to use the Partial Content Update API v2.

POST https://live.luigisbox.com/v2/content

The Index-Object v2

The fundamental unit of data you send is the index-object. Your request body must be a JSON object containing a single root key, objects, which holds an array of these index-objects.

Top-level Request Structure

Parameter Type Required Description
objects Array ✓ An array of one or more objects to be indexed. Recommended batch size: ~100 objects.

Index-Object Parameters (v2)

Each object in the objects array must follow this structure:

Parameter Type Required Description
identity String ✓ A unique identity for the object at the index level. Must match the identity reported by analytics events. See Identity guide.
type String ✓ Object type (e.g., "item", "category", "article"). Different types can be searched separately.
generation String Object generation marker for bulk data synchronization. See Generations.
active_from String ISO 8601 date/time when object should become searchable (e.g., 2019-05-17T21:12:35+00:00).
active_to String ISO 8601 date/time when object should stop being searchable (e.g., 2019-05-17T21:12:35+00:00).
fields Object ✓ Object attributes. Every field is searchable and can be used for filtering. Must include a title field.
nested Array Array of nested objects (categories, variants, etc.) linked to the current object.

Fields Guidelines (v2)

When structuring the fields object in v2:

  • Required: Include a title field - this serves as the object's display name
  • Numeric fields: Format as numbers, not strings ("height": 70.5 not "height": "70.5")
  • Date fields: Use ISO 8601 format with T delimiter ("active_from": "2018-07-15T13:23:50+00:00")
  • Array values: Supported for any field ("color": ["red", "black", "blue"])
  • Nesting: Use only one level of nesting (avoid deeply nested objects)
  • Facets: Any field you send can become a facet for filtering search results
  • v2 Enhancement: Improved handling of nested objects and better performance for large batches

Example: Index-Object v2

{
  "identity": "SKU-XYZ-123-v2",
  "type": "item",
  "generation": "daily-sync-20241014-v2",
  "active_from": "2024-01-01T00:00:00Z",
  "fields": {
    "title": "Premium Quality T-Shirt v2",
    "web_url": "/products/premium-t-shirt-v2",
    "price": 25.50,
    "color": ["Red", "Black", "Blue"],
    "availability": 1,
    "enhanced_metadata": {
      "fabric": "organic cotton",
      "sustainability_score": 8.5
    }
  },
  "nested": [
    {
      "type": "category",
      "identity": "cat-apparel-v2",
      "fields": { 
        "title": "Apparel",
        "display_order": 1
      }
    }
  ]
}

Error Handling (v2)

HTTP Status Description
400 Bad Request The request structure is invalid, JSON is malformed, or some objects failed validation. Check response body for details.
413 Payload Too Large The request exceeds 5 MB (10 MB if compressed). Reduce batch size or enable compression.
429 Too Many Requests The rate limit has been exceeded. Check Retry-After header and see Throttling docs.

Example: Error Response v2

{
  "ok_count": 99,
  "errors_count": 1,
  "errors": {
    "http://example.org/products/1": {
      "type": "malformed_input",
      "reason": "incorrect object format",
      "caused_by": {
        "title": ["must be filled"]
      }
    }
  }
}

v2 Improvements

  • Enhanced nested object processing: Better performance when handling large numbers of nested items
  • Improved error reporting: More detailed error messages with field-level validation feedback
  • Better batch handling: Optimized processing for larger batch sizes
  • Extended metadata support: Enhanced support for complex field structures

Performance Guidelines (v2)

For optimal indexing performance in v2, avoid:

  • High nested count: >15 nested records per object (increased from v1)
  • High field count: >15 fields per object (increased from v1)
  • Large objects: >50KB per object (increased from v1)
  • Large batches: >150 objects per request (increased from v1)