ForSURE.categorylist.models.features.endpoints
FastAPI endpoints for CategorylistItemFeatures operations.
async def get_item_features_api()
Get all features for a specific item.
This endpoint retrieves all features associated with a specific item (identified by item_uuid) within a revision. Features provide additional metadata and properties for items.
Parameters
item_uuid UUID - UUID of the item to get features for.
revision_uuid UUID - UUID of the revision containing the item.
country str, optional - Filter features by country code.
Returns
PaginatedResponse[CategorylistItemFeatures]
Paginated response containing:
- items
list[CategorylistItemFeatures]- List of features for the item - total
int- Total number of features - next_offset
int, optional- Offset for next page - prev_offset
int, optional- Offset for previous page
Example
curl -X GET "https://api.example.com/saas/categorylist/features/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001?country=NL" \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"items": [
{
"uuid": "789e0123-e89b-12d3-a456-426614174002",
"item_uuid": "456e7890-e89b-12d3-a456-426614174001",
"revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
"name": "Feature Name",
"data": {}
}
],
"total": 1,
"next_offset": null,
"prev_offset": null
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to get item features"
}
Note
Requires CATEGORYLIST_VIEW permission.
async def create_item_feature_api()
Create a new feature for an item.
This endpoint creates a new feature and associates it with a specific item. Features provide additional metadata and properties for items.
Parameters
revision_uuid UUID - UUID of the revision containing the item.
item_uuid UUID - UUID of the item to add the feature to.
name str - Name of the feature to create.
data_provider str, optional - Data provider identifier for the feature.
Returns
FeatureCreateResponse
Response containing:
- success
bool- True if feature was created successfully - feature_uuid
str, optional- UUID of the created feature - message
str, optional- Success or error message
Example
curl -X POST "https://api.example.com/saas/categorylist/features/simple/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "name=Custom Feature" \
-F "data_provider=provider1"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"success": true,
"feature_uuid": "789e0123-e89b-12d3-a456-426614174002",
"message": "Feature created successfully"
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to create item feature"
}
Note
Requires CATEGORYLIST_SUGGEST-EDIT permission.
async def create_item_feature_bulk()
Create a feature for multiple items in bulk.
This endpoint creates a feature and applies it to multiple items based on the specified SKU mode. Supports creating features for a single item, items with a prefix, items in a range, or all items.
Parameters
revision_uuid UUID - UUID of the revision containing the items.
sku_mode str - Mode for selecting items:
- current - Apply to a single item (requires item_uuid)
- **prefix** - Apply to all items with SKU starting with sku_prefix
- range - Apply to items with SKU between sku_start and sku_end
- all - Apply to all items in the revision
sku_start str, optional - Starting SKU for range mode.
sku_end str, optional - Ending SKU for range mode.
sku_prefix str, optional - SKU prefix for prefix mode.
item_uuid UUID, optional - Item UUID for current mode.
feature_name str - Name of the feature to create.
data_provider str, optional - Data provider identifier for the feature.
Returns
FeatureCreateResponse
Response containing:
- success
bool- True if feature was created successfully - feature_uuid
str, optional- UUID of the created feature - message
str, optional- Success or error message
Example
curl -X POST "https://api.example.com/saas/categorylist/features/bulk/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "sku_mode=prefix" \
-F "sku_prefix=PROD-" \
-F "feature_name=Bulk Feature" \
-F "data_provider=provider1"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"success": true,
"feature_uuid": "789e0123-e89b-12d3-a456-426614174002",
"message": "Feature created successfully"
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to create item feature"
}
Note
Requires CATEGORYLIST_SUGGEST-EDIT permission. Invalid mode or missing required parameters for the selected mode will result in an error.
async def update_item_feature()
Update a feature for all items that have it.
This endpoint updates a feature across all items that currently have it. The update applies to all instances of the feature in the revision.
Parameters
revision_uuid UUID - UUID of the revision containing the feature.
feature_id UUID - UUID of the feature to update.
column str, optional - Column name to update within the feature.
name str, optional - New name for the feature.
value str, optional - New value for the feature or column.
old_value str, optional - Previous value (for conditional updates).
data_provider str, optional - Data provider identifier.
Returns
FeatureUpdateResponse
Response containing:
- success
bool- True if feature was updated successfully - reload
bool- Whether client should reload data - message
str, optional- Success or error message
Example
curl -X PUT "https://api.example.com/saas/categorylist/features/123e4567-e89b-12d3-a456-426614174000/789e0123-e89b-12d3-a456-426614174002" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "name=Updated Feature Name" \
-F "value=New Value"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"success": true,
"reload": false,
"message": "Feature updated successfully"
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to update item feature"
}
Note
Requires CATEGORYLIST_SUGGEST-EDIT permission. Updates all items that have this feature.
async def delete_item_feature()
Delete a feature from an item.
This endpoint removes a specific feature from a specific item. The feature is only removed from this item, not from other items that may have it.
Parameters
revision_uuid UUID - UUID of the revision containing the item.
item_uuid UUID - UUID of the item to remove the feature from.
feature_id UUID - UUID of the feature to delete.
Returns
FeatureDeleteResponse
Response containing:
- success
bool- True if feature was deleted successfully - message
str, optional- Success or error message
Example
curl -X DELETE "https://api.example.com/saas/categorylist/features/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001/789e0123-e89b-12d3-a456-426614174002" \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"success": true,
"message": "Feature deleted successfully"
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to delete item feature"
}
Note
Requires CATEGORYLIST_SUGGEST-EDIT permission. Feature must exist for the specified item.
async def get_merged_item_data()
Get merged item data (item data + features).
This endpoint retrieves an item's data merged with its features. The merged data combines the base item data with feature values, providing a complete view of the item's properties.
Parameters
sku str - SKU of the item to retrieve.
version str - Version identifier to get the item from.
Returns
MergedItemDataResponse
Response containing:
- sku
str- Item SKU - version
str- Version identifier - merged_data
dict- Combined item data and feature values - features
list[dict]- List of feature objects
Example
curl -X GET "https://api.example.com/saas/categorylist/features/SKU123/merge?version=v1.0" \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"sku": "SKU123",
"version": "v1.0",
"merged_data": {
"general:SKU": "SKU123",
"general:Product Name": "Product",
"Feature Name": "Feature Value"
},
"features": [
{
"name": "Feature Name",
"data_local": {"value": "Feature Value"}
}
]
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to get merged item data"
}
Note
Requires CATEGORYLIST_VIEW permission. Item must exist in the specified version.
async def sync_item_features()
Sync item features (update updated_at timestamp).
This endpoint synchronizes item features by updating the updated_at timestamp. Useful for refreshing feature data without modifying the actual values.
Parameters
revision_uuid UUID - UUID of the revision containing the item.
item_uuid UUID - UUID of the item to sync features for.
feature_id UUID - UUID of the feature to sync.
version str - Version identifier.
Returns
FeatureUpdateResponse
Response containing:
- success
bool- True if sync was successful - reload
bool- Whether client should reload data - message
str, optional- Success or error message
Example
curl -X POST "https://api.example.com/saas/categorylist/features/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001/789e0123-e89b-12d3-a456-426614174002/sync" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "version=v1.0"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"success": true,
"reload": false,
"message": "Item features synced successfully"
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to sync item features"
}
Note
Requires CATEGORYLIST_SUGGEST-EDIT permission. Item must exist and be accessible.
async def search_features()
Search features by name or value.
This endpoint searches for features within a version by name or value. Returns matching features with their associated items.
Parameters
name str, optional - Feature name to search for.
value str, optional - Feature value to search for.
version str - Version identifier to search within.
Returns
dict
Search results containing matching features and their items.
Example
curl -X GET "https://api.example.com/saas/categorylist/features/search?version=v1.0&name=Custom Feature" \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"results": [
{
"feature_uuid": "789e0123-e89b-12d3-a456-426614174002",
"name": "Custom Feature",
"value": "Feature Value",
"items": ["SKU123", "SKU456"]
}
]
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to search features"
}
Note
Requires CATEGORYLIST_VIEW permission. At least one of name or value should be provided.
async def get_feature_statistics()
Get feature statistics for a version.
This endpoint retrieves statistical information about features in a version, including total features, unique SKUs with features, and feature breakdown.
Parameters
version str - Version identifier to get statistics for.
Returns
FeatureStatisticsResponse
Response containing:
- total_features
int- Total number of features in the version - unique_skus_with_features
int- Number of unique SKUs that have features - feature_breakdown
list[FeatureBreakdownEntry]- Breakdown by feature name:- name
str- Feature name - data_provider
str, optional- Data provider identifier - count
int- Number of items with this feature
- name
Example
curl -X GET "https://api.example.com/saas/categorylist/features/stats?version=v1.0" \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example
Successful response
If the request was successful you should receive the status code 200 and
a response body like this:
{
"total_features": 150,
"unique_skus_with_features": 100,
"feature_breakdown": [
{
"name": "Custom Feature",
"data_provider": "provider1",
"count": 50
}
]
}
Error response
If the request failed you might receive status code 400, 401, 403, or 500 with
a response body like this:
{
"detail": "Failed to get feature statistics"
}
Note
Requires CATEGORYLIST_VIEW permission.