# Category Tree Resources
Read Category Trees
## Retrieving a category tree
> Retrieves a category tree.\
> \
> \*\*Note\*\*: By default, only published categories are retrieved.
```json
{"openapi":"3.0.1","info":{"title":"Category","version":"0.0.1"},"tags":[{"name":"Category Tree Resources","description":"Read Category Trees"}],"servers":[{"url":"https://api.emporix.io"}],"security":[],"paths":{"/category/{tenant}/categories/categoryTree":{"get":{"tags":["Category Tree Resources"],"summary":"Retrieving a category tree","description":"Retrieves a category tree.\n\n**Note**: By default, only published categories are retrieved.","operationId":"GET-category-tree-retrieve-category-tree-deprecated","responses":{"200":{"description":"The request was successful. The category tree is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryDeprecated"}}}},"400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"500":{"description":"Some server-side error occurred. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"deprecated":true}}},"components":{"schemas":{"CategoryDeprecated":{"title":"","type":"object","properties":{"id":{"type":"string","description":"Category unique identifier generated when the category is created."},"parentId":{"type":"string","description":"Unique identifier of the parent category."},"name":{"description":"Category name.","oneOf":[{"type":"string","description":"Category name in the default language."},{"type":"object","description":"Map of translations.\nThe keys should be ISO language codes.\nThe values should be category names in specified languages."}]},"code":{"type":"string","description":"Unique category identifier, defined by the user."},"description":{"description":"Category description.","oneOf":[{"type":"string","description":"Category description in the default language."},{"type":"object","description":"Map of translations.\nThe keys should be ISO language codes.\nThe values should be category descriptions in specified languages."}]},"media":{"type":"array","description":"Media files attached to the category.","items":{"type":"object","properties":{"id":{"type":"string","description":"Media file's unique identifier generated when the media file is created."},"url":{"type":"string","description":"Media file's URL."},"tags":{"type":"array","description":"List of media file tags.","items":{"type":"string"}},"contentType":{"type":"string","description":"Media file's MIME type."},"stored":{"type":"boolean","description":"Flag indicating whether the media file is stored in the Category Service."},"uploadLink":{"type":"string","description":"URL where the media file is uploaded, with the file extension specified."}},"additionalProperties":false}},"position":{"minimum":0,"type":"integer","description":"Position in the category tree (on the same category level)."},"published":{"type":"boolean","description":"Flag indicating whether the category has been published or not."},"ecn":{"type":"array","description":"List of external category numbers (ECNs). ","items":{"type":"string"}},"subcategories":{"type":"array","description":"List of direct subcategories.","items":{"$ref":"#/components/schemas/CategoryDeprecated"}},"assignments":{"type":"array","description":"List of resources assigned to the category.","items":{"$ref":"#/components/schemas/AssignmentDeprecated"}}},"description":""},"AssignmentDeprecated":{"type":"object","properties":{"id":{"type":"string","description":"Assignment unique identifier generated when a resource is assigned to a category."},"ref":{"required":["id","type","url"],"type":"object","properties":{"id":{"type":"string","description":"Resource’s unique identifier generated when the resource is created."},"type":{"type":"string","description":"Type of assignment. When assigning products to categories, the value should be set to `product`."},"url":{"type":"string","description":"Resource URL generated when the resource is created."}},"description":"Reference to the resource."}},"description":"Assignment of a resource (such as a product) to a category."},"ErrorMessage":{"title":"error","type":"object","properties":{"status":{"maximum":599,"minimum":100,"type":"integer","description":"Original HTTP error code. It should be consistent with the HTTP response code."},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","type":"string","description":"Classification of the error type.\n\n**Note:** The error type should be written in lowercase and include underscores, for example `validation_failure`."},"message":{"type":"string","description":"Descriptive error message for debugging purposes."},"moreInfo":{"type":"string","description":"More information (such as a link to the documentation) for investigating further and getting support."},"details":{"type":"array","description":"List of problems causing the error.","items":{"title":"errorDetail","required":["type"],"type":"object","properties":{"field":{"type":"string","description":"Element in request data which is causing the error, for example `category.name`.\n\nIf the violation was not field-specific, this field will be empty."},"type":{"pattern":"[a-z]+[a-z_]*[a-z]+","type":"string","description":"Classification of the specific error cause. This value should always be interpreted within the context of the general error type.\n\n**Note:** The error type should be written in lowercase and include underscores, for example `missing_value`."},"message":{"type":"string","description":"Descriptive error message for debugging purposes."},"moreInfo":{"type":"string","description":"More information (such as a link to the documentation) for investigating further and getting support."}},"description":"Specific error cause."}}},"description":"Schema for API-specific errors."}}}}
```
## Retrieving the category trees
> Retrieves the category trees.\
> \*\*\*\
> \
> \### Additional scope info\
> \
> \* \`category.category\_read\_unpublished\` - Only required if the response should contain unpublished categories.
```json
{"openapi":"3.0.1","info":{"title":"Category","version":"0.0.1"},"tags":[{"name":"Category Tree Resources","description":"Read Category Trees"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["category.category_read_unpublished"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"category.category_manage":"Manage a category","category.category_read_unpublished":"Read unpublished categories","category.category_publish":"Publish a category","category.category_unpublish":"Unpublish a category"}}}}},"schemas":{"CategoryTree":{"type":"object","description":"Definition of category tree","required":["id","localizedName","name","position","published"],"properties":{"id":{"type":"string","description":"Category unique identifier generated when the category is created."},"name":{"type":"string","description":"Category name in tenant default language.","deprecated":true},"description":{"type":"string","description":"Description in tenant default language.","deprecated":true},"code":{"type":"string","description":"Unique category identifier defined by the tenant.","deprecated":true},"localizedName":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category name as a map of translations."},"localizedDescription":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category description as a map of translations."},"localizedSlug":{"type":"object","additionalProperties":{"type":"string"},"description":"Provides localized category name or code without diacritics for the URL."},"validity":{"$ref":"#/components/schemas/Validity","description":"Category validity."},"position":{"type":"integer","format":"int32","description":"Category position in relation to sibling categories."},"published":{"type":"boolean","description":"Flag indicating whether the category has been published."},"ecn":{"type":"array","description":"List of external category numbers (ECNs) unique for each category.","items":{"type":"string"}},"subcategories":{"type":"array","description":"Subcategories of this category.","items":{"$ref":"#/components/schemas/CategoryTree"}}}},"Validity":{"type":"object","properties":{"from":{"type":"string","description":"Date and time from which the category is valid compliant with the ISO 8601 standard.","format":"date-time"},"to":{"type":"string","description":"Date and time to which the category is valid compliant with the ISO 8601 standard.","format":"date-time"}}},"ErrorResponse":{"required":["code","details","message","status"],"type":"object","properties":{"resourceId":{"type":"string","nullable":true},"code":{"type":"integer","format":"int32"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/category/{tenant}/category-trees":{"get":{"tags":["Category Tree Resources"],"summary":"Retrieving the category trees","description":"Retrieves the category trees.\n***\n\n### Additional scope info\n\n* `category.category_read_unpublished` - Only required if the response should contain unpublished categories.\n","operationId":"GET-category-tree-retrieve-category-tree","parameters":[{"name":"tenant","in":"path","description":"Your Emporix tenant name.\n\n**Note**: The tenant should always be written in lowercase.\n","required":true,"schema":{"type":"string"}},{"name":"showUnpublished","in":"query","description":"If set to `true`, not published categories are retrieved as well.\nPossible values:\n* `true`\n* `false`\n\n**Note**: To get unpublished categories you need to have `category.category_read_unpublished` scope.\n","schema":{"type":"boolean","default":false}},{"name":"categoryIds","in":"query","description":"List of category IDs. If provided, the response returns only the category trees that include at least one of the specified categories.\n","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"The request was successful. The category tree is returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryTree"}}}}},"403":{"description":"Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Searching for category trees
> Searches for category trees.\
> \*\*\*\
> \### Additional scope info\
> \
> \* \`category.category\_read\_unpublished\` - Only required if the response should contain unpublished categories.
```json
{"openapi":"3.0.1","info":{"title":"Category","version":"0.0.1"},"tags":[{"name":"Category Tree Resources","description":"Read Category Trees"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["category.category_read_unpublished"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"category.category_manage":"Manage a category","category.category_read_unpublished":"Read unpublished categories","category.category_publish":"Publish a category","category.category_unpublish":"Unpublish a category"}}}}},"schemas":{"CategoryTreeSearchRequest":{"required":["categoryIds"],"type":"object","properties":{"categoryIds":{"type":"array","items":{"type":"string"},"description":"List of category IDs. If provided, the response returns only the category trees that include at least one of the specified categories."}}},"CategoryTree":{"type":"object","description":"Definition of category tree","required":["id","localizedName","name","position","published"],"properties":{"id":{"type":"string","description":"Category unique identifier generated when the category is created."},"name":{"type":"string","description":"Category name in tenant default language.","deprecated":true},"description":{"type":"string","description":"Description in tenant default language.","deprecated":true},"code":{"type":"string","description":"Unique category identifier defined by the tenant.","deprecated":true},"localizedName":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category name as a map of translations."},"localizedDescription":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category description as a map of translations."},"localizedSlug":{"type":"object","additionalProperties":{"type":"string"},"description":"Provides localized category name or code without diacritics for the URL."},"validity":{"$ref":"#/components/schemas/Validity","description":"Category validity."},"position":{"type":"integer","format":"int32","description":"Category position in relation to sibling categories."},"published":{"type":"boolean","description":"Flag indicating whether the category has been published."},"ecn":{"type":"array","description":"List of external category numbers (ECNs) unique for each category.","items":{"type":"string"}},"subcategories":{"type":"array","description":"Subcategories of this category.","items":{"$ref":"#/components/schemas/CategoryTree"}}}},"Validity":{"type":"object","properties":{"from":{"type":"string","description":"Date and time from which the category is valid compliant with the ISO 8601 standard.","format":"date-time"},"to":{"type":"string","description":"Date and time to which the category is valid compliant with the ISO 8601 standard.","format":"date-time"}}},"ErrorResponse":{"required":["code","details","message","status"],"type":"object","properties":{"resourceId":{"type":"string","nullable":true},"code":{"type":"integer","format":"int32"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/category/{tenant}/category-trees/search":{"post":{"tags":["Category Tree Resources"],"summary":"Searching for category trees","description":"Searches for category trees.\n***\n### Additional scope info\n\n* `category.category_read_unpublished` - Only required if the response should contain unpublished categories.\n","operationId":"POST-category-tree-search-category-trees","parameters":[{"name":"tenant","in":"path","description":"Your Emporix tenant name.\n\n**Note**: The tenant should always be written in lowercase.\n","required":true,"schema":{"type":"string"}},{"name":"showUnpublished","in":"query","description":"If set to `true`, not published categories are retrieved as well.\nPossible values:\n* `true`\n* `false`\n\n**Note**: To get unpublished categories you need to have `category.category_read_unpublished` scope.\n","schema":{"type":"boolean","default":false}},{"name":"Content-Language","in":"header","description":"The Content-Language request HTTP header defines language(s) that can be used in the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:\n* `*` - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.\n* `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).\n\n**Note**: For category requests, localized fields (such as `localizedName`, `localizedDescription`, `localizedSlug`) must always be provided as maps of language codes to values, regardless of the Content-Language header value.\n","schema":{"type":"string","default":"*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryTreeSearchRequest"}}},"required":true},"responses":{"200":{"description":"The request was successful. The category tree is returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryTree"}}}}},"400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Retrieving a specific category tree
> Retrieves a category tree for a root category with a given id.\
> \
> \*\*Note:\*\* You can retrieve a category tree only for a root category. It is not possible to get a category tree for a category that lies lower in the hierarchy.\
> \*\*\*\
> \
> \### Additional scope info\
> \
> \* \`category.category\_read\_unpublished\` - Only required if the response should contain unpublished categories.
```json
{"openapi":"3.0.1","info":{"title":"Category","version":"0.0.1"},"tags":[{"name":"Category Tree Resources","description":"Read Category Trees"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["category.category_read_unpublished"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"category.category_manage":"Manage a category","category.category_read_unpublished":"Read unpublished categories","category.category_publish":"Publish a category","category.category_unpublish":"Unpublish a category"}}}}},"schemas":{"CategoryTree":{"type":"object","description":"Definition of category tree","required":["id","localizedName","name","position","published"],"properties":{"id":{"type":"string","description":"Category unique identifier generated when the category is created."},"name":{"type":"string","description":"Category name in tenant default language.","deprecated":true},"description":{"type":"string","description":"Description in tenant default language.","deprecated":true},"code":{"type":"string","description":"Unique category identifier defined by the tenant.","deprecated":true},"localizedName":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category name as a map of translations."},"localizedDescription":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized category description as a map of translations."},"localizedSlug":{"type":"object","additionalProperties":{"type":"string"},"description":"Provides localized category name or code without diacritics for the URL."},"validity":{"$ref":"#/components/schemas/Validity","description":"Category validity."},"position":{"type":"integer","format":"int32","description":"Category position in relation to sibling categories."},"published":{"type":"boolean","description":"Flag indicating whether the category has been published."},"ecn":{"type":"array","description":"List of external category numbers (ECNs) unique for each category.","items":{"type":"string"}},"subcategories":{"type":"array","description":"Subcategories of this category.","items":{"$ref":"#/components/schemas/CategoryTree"}}}},"Validity":{"type":"object","properties":{"from":{"type":"string","description":"Date and time from which the category is valid compliant with the ISO 8601 standard.","format":"date-time"},"to":{"type":"string","description":"Date and time to which the category is valid compliant with the ISO 8601 standard.","format":"date-time"}}},"ErrorResponse":{"required":["code","details","message","status"],"type":"object","properties":{"resourceId":{"type":"string","nullable":true},"code":{"type":"integer","format":"int32"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/category/{tenant}/category-trees/{categoryId}":{"get":{"tags":["Category Tree Resources"],"summary":"Retrieving a specific category tree","description":"Retrieves a category tree for a root category with a given id.\n\n**Note:** You can retrieve a category tree only for a root category. It is not possible to get a category tree for a category that lies lower in the hierarchy.\n***\n\n### Additional scope info\n\n* `category.category_read_unpublished` - Only required if the response should contain unpublished categories.\n","operationId":"GET-category-tree-retrieve-category-tree-by-id","parameters":[{"name":"tenant","in":"path","description":"Your Emporix tenant name.\n\n**Note**: The tenant should always be written in lowercase.\n","required":true,"schema":{"type":"string"}},{"name":"categoryId","in":"path","description":"A unique identifier of a root category, generated when the category is created.\n","required":true,"deprecated":false,"allowEmptyValue":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"showUnpublished","in":"query","description":"If set to `true`, not published categories are retrieved as well.\nPossible values:\n* `true`\n* `false`\n\n**Note**: To get unpublished categories you need to have `category.category_read_unpublished` scope.\n","schema":{"type":"boolean","default":false}},{"name":"Content-Language","in":"header","description":"The Content-Language request HTTP header defines language(s) that can be used in the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:\n* `*` - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.\n* `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).\n\n**Note**: For category requests, localized fields (such as `localizedName`, `localizedDescription`, `localizedSlug`) must always be provided as maps of language codes to values, regardless of the Content-Language header value.\n","schema":{"type":"string","default":"*"}}],"responses":{"200":{"description":"The request was successful. The category tree is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryTree"}}}},"403":{"description":"Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Category tree with specified id does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.emporix.io/api-references-1/readme/api-reference-6/category-tree-resources.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.