Category Resources
Manage Categories
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2If set to true, only root categories (categories without parents) are retrieved.
Possible values:
truefalse
falseExample: trueIf set to true, not published categories are retrieved as well.
Possible values:
truefalseNote: To get unpublished categories you need to havecategory.category_read_unpublishedscope.
falseExample: truePage number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.
1Number of export files to be retrieved per page.
60List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden. Possible values:
{fieldName}:ASC{fieldName}:DESC{fieldName}:ASC,{fieldName2}:DESC{internationalizedFieldName.en}:ASC- contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.{internationalizedFieldName}:ASC- contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
{fieldName}:ASC,{fieldName2}:DESCSearch by the code value. The equal case insensitive operator is used for this parameter therefore the provided value must exactly match the stored value.
3A001Search by the localizedName of the categories, it will be conformed against all of the specified accepted-languages.
Example category nameSearch by the localizeDescription of the categories, it will be conformed against all of the specified accepted-languages.
Example category descriptionSearch by the localizedSlug of the categories, it will be conformed against all of the specified accepted-languages.
Example category slugSearch by the ECN value. The equal operator is used for this parameter therefore the provided value must exactly match the stored value.
3A001Search by categories with 'validity.from' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.
2022-11-01Search by categories with 'validity.to' date field which is before than specified value. It must follow the pattern: 'yyyy-MM-dd'.
1997-11-01Search by categories with 'metadata.modifiedAt' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.
2022-01-28List of properties used to project and sort the results, separated by commas. Possible values:
*- each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.en,en,de- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$The header value indicates if the total count of entities should be returned. Possible values:
truefalseDefault value:false
falseExample: trueGET /category/{tenant}/categories HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
[
{
"id": "text",
"parentId": "text",
"localizedName": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedDescription": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedSlug": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"code": "text",
"ecn": [
"text"
],
"Validity": {
"from": "2025-07-09T02:46:54.766Z",
"to": "2025-07-09T02:46:54.766Z"
},
"position": 1,
"published": true,
"supercategoriesIds": [
"text"
],
"mixins": {},
"Metadata": {
"createdAt": "2025-07-09T02:46:54.766Z",
"modifiedAt": "2025-07-09T02:46:54.766Z",
"version": 1,
"mixins": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"media": [
{
"id": "345-12345",
"url": "https://emporix.com/platform/saas-ag/media/v2/public/files/12345678",
"contentType": "image/jpeg",
"metadata": {
"createdAt": "2022-12-06T06:54:36.834Z"
},
"customAttributes": {
"id": "345-54353",
"height": 1234,
"width": 1024,
"sizeKB": 5,
"type": "jpg",
"name": "ima.jpg"
}
}
]
}
]Creates a new category. Creating category as a root may be achieved by adding the 'parentId' field with a 'root' value or by not providing the 'parentId' in the payload.
Required scopes
category.category_managecategory.category_publishNote: The
category.category_publishscope is only required if you want to publish the category when creating it.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:
truefalseNote: To publish a category you need to havecategory.category_publishscope. Note: To unpublish a category you need to havecategory.category_unpublishscope.
falseExample: trueThe Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:
*- request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.en,en,de,fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$Custom category identifier. If not provided, it is automatically generated
Unique identifier of the parent category. No parentId in the body indicates that this is a root category.
List of external category numbers (ECNs) unique for every category.
Unique category identifier, defined by the tenant.
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.
Flag indicating whether the category has been published or not.
POST /category/{tenant}/categories HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 380
{
"parentId": "056bcaf6-66b8-4ddd-9489-65c5f6449e74",
"localizedName": {
"en": "Floor Care",
"de": "Bodenpflege"
},
"localizedDescription": {
"en": "Floor Care",
"de": "Bodenpflege"
},
"localizedSlug": {
"en": "Floor-Care",
"de": "Bodenpflege"
},
"ecn": [
"AX6784",
"123078",
"SJUIOKM"
],
"validity": {
"from": "2022-01-05T12:44:51.871Z",
"to": "2022-12-05T23:59:59.000Z"
},
"position": 5,
"published": true,
"mixins": {}
}{
"id": "084bcaf6-66b8-4ddd-9489-65c5f6449e94"
}Retrieves a specified category and its details using the category ID.
Note: If you want to retrieve the category details using the code, you can do this by using the GET endpoint for retrieving a list of categories with the code query parameter.
Required scopes
category.category_read_unpublishedNote: Only required if the response should contain unpublished categories.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier generated when the category is created.
084bcaf6-66b8-4ddd-9489-65c5f6449e94If set to true, not published categories are retrieved as well.
Possible values:
truefalseNote: To get unpublished categories you need to havecategory.category_read_unpublishedscope.
falseExample: trueList of properties used to project and sort the results, separated by commas. Possible values:
*- each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.en,en,de- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$GET /category/{tenant}/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
{
"id": "text",
"parentId": "text",
"localizedName": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedDescription": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedSlug": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"code": "text",
"ecn": [
"text"
],
"Validity": {
"from": "2025-07-09T02:46:54.766Z",
"to": "2025-07-09T02:46:54.766Z"
},
"position": 1,
"published": true,
"supercategoriesIds": [
"text"
],
"mixins": {},
"Metadata": {
"createdAt": "2025-07-09T02:46:54.766Z",
"modifiedAt": "2025-07-09T02:46:54.766Z",
"version": 1,
"mixins": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"media": [
{
"id": "345-12345",
"url": "https://emporix.com/platform/saas-ag/media/v2/public/files/12345678",
"contentType": "image/jpeg",
"metadata": {
"createdAt": "2022-12-06T06:54:36.834Z"
},
"customAttributes": {
"id": "345-54353",
"height": 1234,
"width": 1024,
"sizeKB": 5,
"type": "jpg",
"name": "ima.jpg"
}
}
]
}Fully updates a specified category by replacing existing information or creating a new one if there is no category with the given id.
Version specified in the metadata field must be the same as in the database. The version can be omitted but then optimistic locking is not be enabled. Category-to-root promotion may be achieved by adding the parentId field with the root value or by excluding the parentId from the payload.
Required scopes
category.category_managecategory.category_publishNote: Thecategory.category_publishscope is only required if you want to publish the category when updating it.category.category_unpublishNote: Only required if you want to unpublish the category when updating it.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier either existing category id or custom id that will be used to create a new category.
084bcaf6-66b8-4ddd-9489-65c5f6449e94If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:
truefalseNote: To publish a category you need to havecategory.category_publishscope. Note: To unpublish a category you need to havecategory.category_unpublishscope.
falseExample: trueThe Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:
*- request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.en,en,de,fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$Unique identifier of the parent category. No parentId in the body indicates that this is a root category.
List of external category numbers (ECNs) unique for every category.
Unique category identifier, defined by the tenant.
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.
Flag indicating whether the category has been published or not.
PUT /category/{tenant}/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 405
{
"parentId": "084bcaf6-66b8-4ddd-9489-65c5f6449e94",
"localizedName": {
"en": "Floor Care",
"de": "Bodenpflege"
},
"localizedDescription": {
"en": "Floor Care",
"de": "Bodenpflege"
},
"localizedSlug": {
"en": "Floor Care",
"de": "Bodenpflege"
},
"ecn": [
"AX6784",
"123078",
"SJUIOKM"
],
"validity": {
"from": "2022-01-05T12:44:51.871Z",
"to": "2022-12-05T23:59:59.000Z"
},
"position": 5,
"published": true,
"mixins": {},
"metadata": {
"version": 1
}
}{
"id": "084bcaf6-66b8-4ddd-9489-65c5f6449e94"
}Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier generated when the category is created.
084bcaf6-66b8-4ddd-9489-65c5f6449e94Deprecated name : "recursive".
If set to true, all descendants of the specified category will be deleted as well.
If set to false, direct subcategories of the specified category will become top-level categories. Relations between the subcategories and their descendants will be preserved.
Possible values:
truefalseNote: To delete a category you need to havecategory.category_managescope.
falseExample: trueTo use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$DELETE /category/{tenant}/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
{}Partially updates a specified category. Version specified in the 'metadata' field must be the same as in the database. Category-to-root promotion may be achieved by adding 'parentId' field with the 'root' value.
Required scopes
category.category_managecategory.category_publishNote: Thecategory.category_publishscope is only required if you want to publish the category when creating it.category.category_unpublishNote: Only required if you want to unpublish the category when updating it.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier generated when the category is created.
084bcaf6-66b8-4ddd-9489-65c5f6449e94If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:
truefalseNote: To publish a category you need to havecategory.category_publishscope. Note: To unpublish a category you need to havecategory.category_unpublishscope.
falseExample: trueThe Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:
*- request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.en,en,de,fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$Unique identifier of the parent category. No parentId in the body indicates that this is a root category.
List of external category numbers (ECNs) unique for every category.
Unique category identifier, defined by the tenant.
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.
Flag indicating whether the category has been published or not.
PATCH /category/{tenant}/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 144
{
"localizedName": {
"en": "Floor Care Liquids"
},
"localizedSlug": {
"en": "Floor-Care-Liquids"
},
"position": 3,
"published": true,
"metadata": {
"version": 1
}
}{}Retrieves a list of parents for a specified category. Parents are sorted in ascending order from root to leaf by default.
If there are unpublished categories in the category tree, then if the parameter showUnpublished=false is used, unpublished category parents will be omitted in the response.
Required scopes
category.category_read_unpublishedNote: Only required if the response should contain unpublished categories.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier generated when the category is created.
084bcaf6-66b8-4ddd-9489-65c5f6449e94If set to true, not published categories are retrieved as well.
Possible values:
truefalseNote: To get unpublished categories you need to havecategory.category_read_unpublishedscope.
falseExample: truePage number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.
1Number of export files to be retrieved per page.
60List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden. Possible values:
{fieldName}:ASC{fieldName}:DESC{fieldName}:ASC,{fieldName2}:DESC{internationalizedFieldName.en}:ASC- contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.{internationalizedFieldName}:ASC- contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
{fieldName}:ASC,{fieldName2}:DESCList of properties used to project and sort the results, separated by commas. Possible values:
*- each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.en,en,de- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$The header value indicates if the total count of entities should be returned. Possible values:
truefalseDefault value:false
falseExample: trueGET /category/{tenant}/categories/{categoryId}/parents HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
[
{
"id": "text",
"parentId": "text",
"localizedName": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedDescription": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedSlug": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"code": "text",
"ecn": [
"text"
],
"Validity": {
"from": "2025-07-09T02:46:54.766Z",
"to": "2025-07-09T02:46:54.766Z"
},
"position": 1,
"published": true,
"supercategoriesIds": [
"text"
],
"mixins": {},
"Metadata": {
"createdAt": "2025-07-09T02:46:54.766Z",
"modifiedAt": "2025-07-09T02:46:54.766Z",
"version": 1,
"mixins": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"media": [
{
"id": "345-12345",
"url": "https://emporix.com/platform/saas-ag/media/v2/public/files/12345678",
"contentType": "image/jpeg",
"metadata": {
"createdAt": "2022-12-06T06:54:36.834Z"
},
"customAttributes": {
"id": "345-54353",
"height": 1234,
"width": 1024,
"sizeKB": 5,
"type": "jpg",
"name": "ima.jpg"
}
}
]
}
]Retrieves a list of subcategories for a specified category.
If there are unpublished categories in the category tree, then when the showUnpublished=false parameter is used, only subcategories up to the last published subcategory will be shown.
Required scopes
category.category_read_unpublishedNote: Only required if the response should contain unpublished categories.
Your Emporix tenant's name.
Note: The tenant should always be written in lowercase.
saasdev2Category's unique identifier generated when the category is created.
084bcaf6-66b8-4ddd-9489-65c5f6449e94You can limit the depth of retrieved subcategories with the depth parameter.
If not specified, all descendant categories are retrieved.
Possible values:
integer >= 1
Note: 'depth=1' means that only direct children of the category will be retrieved
If set to true, not published categories are retrieved as well.
Possible values:
truefalseNote: To get unpublished categories you need to havecategory.category_read_unpublishedscope.
falseExample: truePage number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.
1Number of export files to be retrieved per page.
60List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden. Possible values:
{fieldName}:ASC{fieldName}:DESC{fieldName}:ASC,{fieldName2}:DESC{internationalizedFieldName.en}:ASC- contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.{internationalizedFieldName}:ASC- contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
{fieldName}:ASC,{fieldName2}:DESCList of properties used to project and sort the results, separated by commas. Possible values:
*- each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.en,en,de- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5- each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
*Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`To use this endpoint you have to add X-Version header with proper value to your request.
Note: The header value has to match following regular expression: ^v[1-9][0-9]?$
v2Pattern: ^v[1-9][0-9]?$The header value indicates if the total count of entities should be returned. Possible values:
truefalseDefault value:false
falseExample: trueGET /category/{tenant}/categories/{categoryId}/subcategories HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
[
{
"id": "text",
"parentId": "text",
"localizedName": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedDescription": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"localizedSlug": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"code": "text",
"ecn": [
"text"
],
"Validity": {
"from": "2025-07-09T02:46:54.766Z",
"to": "2025-07-09T02:46:54.766Z"
},
"position": 1,
"published": true,
"supercategoriesIds": [
"text"
],
"mixins": {},
"Metadata": {
"createdAt": "2025-07-09T02:46:54.766Z",
"modifiedAt": "2025-07-09T02:46:54.766Z",
"version": 1,
"mixins": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"media": [
{
"id": "345-12345",
"url": "https://emporix.com/platform/saas-ag/media/v2/public/files/12345678",
"contentType": "image/jpeg",
"metadata": {
"createdAt": "2022-12-06T06:54:36.834Z"
},
"customAttributes": {
"id": "345-54353",
"height": 1234,
"width": 1024,
"sizeKB": 5,
"type": "jpg",
"name": "ima.jpg"
}
}
]
}
]Was this helpful?