Endpoint Summary
This table provides quick access to the general search service under the Search section. Detailed request and response fields are included under the relevant section.
| No | Service | Endpoint |
|---|---|---|
| 1 | Search | POST /api/v1/search |
General Technical Information
For the Search endpoint on this page, authentication information is sent in the request body.
ClientId and AppKey fields are required.
This endpoint is used to perform centralized search across multiple entity types in PIM.
The search scope is determined by the EntityTypes field.
SearchKey represents the text searched by the user.
It works with the same logic as the value entered in the global search bar in the UI.
In the response, results are returned as separate arrays according to entity types such as product, variant, category, and trademark. This structure makes it easier to group results under headings on the UI side.
PageIndex and PageSize fields can be used in search results.
PageIndex starts from 0.
Search is a general search service used to provide fast access across catalog data. Product, variant, category, and trademark records can be queried with a single request.
This endpoint does not create or update data; it only returns existing records that match the search criteria.
1. Search — POST /api/v1/search
This endpoint is used to perform the searches made through the global search bar in the PIM UI through the API. You can search across different entity types such as Product, Variant, Category, and Trademark at the same time.
SearchKeyis required and represents the text to be searched.EntityTypesis required and determines which entity types will be included in the search.- Multiple entity types can be sent to perform a multi-entity search within a single request.
- In the response, each entity type is returned as a separate array. If there are no results for an entity type, the related array may be returned empty.
- The search response may return summary or model information for the related entity records. For detailed fields, it can be used together with the relevant query endpoints.
Entity Type Values
The EntityTypes array determines the data types to be searched.
| Value | Entity Type | Description |
|---|---|---|
0 | Product | Used to search product records. |
1 | Variant | Used to search variant records. |
2 | Category | Used to search category records. |
3 | Trademark | Used to search trademark records. |
Search Usage Notes
- The global search screen can be used to show results from different entity types in a single place.
- If the user will be redirected to a detail page, the related record ID and entity type in the response should be evaluated together.
- If details of product or variant records returned in the search results are needed, they can be queried separately through the Product or Variant query endpoints.
- If the search scope needs to be narrowed, only the target entity types should be sent in the
EntityTypesfield.
Endpoint-Specific Query Parameters
| API Parameter | Type | Required | PIM UI Equivalent / Meaning | Description |
|---|---|---|---|---|
SearchKey |
string |
✅ | Search Bar Text | Search keyword entered in the search bar at the top of the UI. |
EntityTypes |
array (integer) |
✅ | Search Scope | Determines which entity types will be searched. 0 = Product, 1 = Variant, 2 = Category, 3 = Trademark. |
API Response Parameters and UI Equivalents
Each SearchResultPayload object in the Result array returns the entities found in the search grouped by type:
| API Response Field | Type | PIM UI Equivalent / Field Name | Description |
|---|---|---|---|
Products |
array |
Product Search Results | List of products matching the search criteria. Each item is in the Product structure. |
ProductVariants |
array |
Variant Search Results | List of variants matching the search criteria. |
Categories |
array |
Category Search Results | List of categories matching the search criteria. Each item is in the Category structure. |
Trademarks |
array |
Trademark Search Results | List of trademarks matching the search criteria. Each item is in the Trademark structure. |
Usage Guide in the UI
- Multi-Entity Search: The search bar in the UI searches across multiple entity types at the same time. You can achieve the same behavior through the API by adding multiple values to the
EntityTypesarray, such as[0, 1, 2, 3]to search across all types. - Search Result Groups: In the API response, results are returned in separate arrays by entity type. In the UI, results are also grouped under headings such as Products, Variants, Categories, and Trademarks.
- Pagination: Search results can also be paginated.
PageIndexandPageSizeparameters are also valid here. The defaultPageSizevalue is20.
Common Error Cases
The table below is prepared for the common error cases that may apply to the Search endpoint.
Detail messages can be tracked through the Message, Details, or Errors fields in the response.
| HTTP Status | Status | Error Message |
|---|---|---|
400 | Bad Request | |
401 | Unauthorized | |
403 | Forbidden | |
404 | Not Found | |
422 | Unprocessable Entity | |
429 | Too Many Requests | |
500 | Internal Server Error |