Partial Content Update (PATCH) v2
Update specific fields of existing objects without sending the full payload using the v2 Partial Content Update API endpoint.
This endpoint requires HMAC authentication. Refer to the Authentication documentation for details.
Overview
This is the v2 version of the Partial Content Update API endpoint. This endpoint is ideal for making small, frequent updates to existing objects, such as changing a product's price, description, or availability. You only need to send the identity of the object and the specific fields you wish to add or modify.
Key Behaviour (v2):
- This operation is incremental; it does not affect fields you omit from the request.
- It cannot be used to create new objects. If an
identityis not found, it will result in an error. - You cannot change an object's
type. - v2 Enhancement: Improved batch processing and better field validation.
Common Use Cases:
- Updating prices or stock levels
- Adding a new promotional label or updating a product description.
- Changing
availabilitystatus - Synchronizing real-time data from your database to the search index without a full re-index.
The batch limit for this endpoint is 300 objects per request.
For adding new products or completely overwriting existing ones, use the Content Update (POST) v2 endpoint instead. This endpoint is only for modifying existing objects.
https://live.luigisbox.com/v2/content
Request Parameters (v2)
The root of your request body must be a JSON object containing a single key, objects.
Top-level Request Structure
| Parameter | Type | Required | Description |
|---|---|---|---|
objects |
Array | ✓ | An array of one or more objects to be partially updated. |
Object Structure (v2)
Each object in the objects array must contain an identity and the fields you wish to change.
| Parameter | Type | Required | Description |
|---|---|---|---|
identity |
String | ✓ | The unique identifier of the object you want to update. |
fields |
Object | A key-value map of the attributes to add or modify. Enhanced validation in v2. | |
nested |
Array | An array of nested objects. Warning: Sending this key will replace the entire existing nested array for the object. |
Example: Request Body (JSON) v2
{
"objects": [
{
"identity": "product-001-v2",
"fields": {
"price": 44.99,
"updated_at": "2024-10-20T15:30:00Z",
"v2_metadata": {
"enhanced_features": true
}
}
},
{
"identity": "product-002-v2",
"fields": {
"description": "Now with v2 enhanced, more detailed description!",
"performance_score": 9.2
}
}
]
}
Error Handling (v2)
| HTTP Status | Description |
|---|---|
| 400 Bad Request | The request structure is invalid, the JSON is malformed, or an object was not found. Enhanced error details in v2. |
| 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": 1,
"errors_count": 1,
"errors": {
"product-001-v2": {
"type": "not_found",
"reason": "Identity not in catalog",
"v2_details": {
"suggested_action": "Create object first using POST /v2/content"
}
}
}
}
v2 Improvements
- Enhanced validation: Better field-level validation with more detailed error messages
- Improved performance: Faster processing for large batches of partial updates
- Better error reporting: More comprehensive error details with suggested actions
- Extended field support: Enhanced support for complex field structures and metadata
Performance Guidelines (v2)
For optimal partial update performance in v2:
- Batch size: Up to 300 objects per request (same as v1)
- Field complexity: Enhanced support for nested field structures
- Real-time updates: Optimized for frequent, small updates
Related Endpoints
- Content Update v2 - Create or replace objects
- Content Removal v2 - Delete objects from index
- Update by Query v2 - Bulk updates based on search criteria