Category Resources

Manage Categories

Retrieving a list of categories

get

Retrieves a list of categories for a given tenant.


Required scopes

  • category.category_read_unpublished

    Note: Only required if the response should contain unpublished categories.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
Query parameters
showRootsbooleanOptional

If set to true, only root categories (categories without parents) are retrieved. Possible values:

  • true
  • false
Default: falseExample: true
showUnpublishedbooleanOptional

If set to true, not published categories are retrieved as well. Possible values:

  • true
  • false Note: To get unpublished categories you need to have category.category_read_unpublished scope.
Default: falseExample: true
pageNumberinteger · int32 · min: 1Optional

Page 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.

Default: 1
pageSizeinteger · int32 · min: 1Optional

Number of export files to be retrieved per page.

Default: 60
sortstringOptional

List 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.
Example: {fieldName}:ASC,{fieldName2}:DESC
codestringOptional

Search by the code value. The equal case insensitive operator is used for this parameter therefore the provided value must exactly match the stored value.

Example: 3A001
localizedNamestringOptional

Search by the localizedName of the categories, it will be conformed against all of the specified accepted-languages.

Example: Example category name
localizedDescriptionstringOptional

Search by the localizeDescription of the categories, it will be conformed against all of the specified accepted-languages.

Example: Example category description
localizedSlugstringOptional

Search by the localizedSlug of the categories, it will be conformed against all of the specified accepted-languages.

Example: Example category slug
ecnstringOptional

Search by the ECN value. The equal operator is used for this parameter therefore the provided value must exactly match the stored value.

Example: 3A001
validityFromstringOptional

Search by categories with 'validity.from' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.

Example: 2022-11-01
validityTostringOptional

Search by categories with 'validity.to' date field which is before than specified value. It must follow the pattern: 'yyyy-MM-dd'.

Example: 1997-11-01
metadataModifiedAtstringOptional

Search by categories with 'metadata.modifiedAt' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.

Example: 2022-01-28
Header parameters
Accept-LanguagestringOptional

List 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.
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
X-Total-CountbooleanOptional

The header value indicates if the total count of entities should be returned. Possible values:

  • true
  • false Default value: false
Default: falseExample: true
Responses
200
The request was successful. The categories are returned.
application/json
get
GET /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-17T14:12:23.758Z",
      "to": "2025-07-17T14:12:23.758Z"
    },
    "position": 1,
    "published": true,
    "supercategoriesIds": [
      "text"
    ],
    "mixins": {},
    "Metadata": {
      "createdAt": "2025-07-17T14:12:23.758Z",
      "modifiedAt": "2025-07-17T14:12:23.758Z",
      "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"
        }
      }
    ]
  }
]

Creating a new category

post

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_manage

  • category.category_publish

    Note: The category.category_publish scope is only required if you want to publish the category when creating it.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
Query parameters
publishbooleanOptional

If 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:

  • true
  • false Note: To publish a category you need to have category.category_publish scope. Note: To unpublish a category you need to have category.category_unpublish scope.
Default: falseExample: true
Header parameters
Content-LanguagestringOptional

The 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) .
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
Body
idstringOptional

Custom category identifier. If not provided, it is automatically generated

parentIdstring | nullableOptional

Unique identifier of the parent category. No parentId in the body indicates that this is a root category.

ecnstring[] | nullableOptional

List of external category numbers (ECNs) unique for every category.

codestring | nullableOptional

Unique category identifier, defined by the tenant.

positioninteger · int32 | nullableOptional

Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.

publishedbooleanRequired

Flag indicating whether the category has been published or not.

Responses
201
The category has been successfully created.
application/json
post
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"
}

Retrieving a category's details

get

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_unpublished

    Note: Only required if the response should contain unpublished categories.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
showUnpublishedbooleanOptional

If set to true, not published categories are retrieved as well. Possible values:

  • true
  • false Note: To get unpublished categories you need to have category.category_read_unpublished scope.
Default: falseExample: true
Header parameters
Accept-LanguagestringOptional

List 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.
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
Responses
200
The request was successful. The category is returned.
application/json
get
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-17T14:12:23.758Z",
    "to": "2025-07-17T14:12:23.758Z"
  },
  "position": 1,
  "published": true,
  "supercategoriesIds": [
    "text"
  ],
  "mixins": {},
  "Metadata": {
    "createdAt": "2025-07-17T14:12:23.758Z",
    "modifiedAt": "2025-07-17T14:12:23.758Z",
    "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"
      }
    }
  ]
}

Upserting a category

put

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_manage

  • category.category_publish Note: The category.category_publish scope is only required if you want to publish the category when updating it.

  • category.category_unpublish Note: Only required if you want to unpublish the category when updating it.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier either existing category id or custom id that will be used to create a new category.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
publishbooleanOptional

If 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:

  • true
  • false Note: To publish a category you need to have category.category_publish scope. Note: To unpublish a category you need to have category.category_unpublish scope.
Default: falseExample: true
Header parameters
Content-LanguagestringOptional

The 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) .
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
Body
parentIdstring | nullableOptional

Unique identifier of the parent category. No parentId in the body indicates that this is a root category.

ecnstring[] | nullableOptional

List of external category numbers (ECNs) unique for every category.

codestring | nullableOptional

Unique category identifier, defined by the tenant.

positioninteger · int32 | nullableOptional

Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.

publishedbooleanRequired

Flag indicating whether the category has been published or not.

metadataall ofOptional
Responses
201
The category has been successfully created
application/json
put
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"
}

Deleting a category

delete

Deletes a specified category.

Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
withSubcategoriesbooleanOptional

Deprecated 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:

  • true
  • false Note: To delete a category you need to have category.category_manage scope.
Default: falseExample: true
Header parameters
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
Responses
204
The category was successfully deleted.
application/json
Responseobject
delete
DELETE /category/{tenant}/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
{}

Updating a category

patch

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_manage

  • category.category_publish Note: The category.category_publish scope is only required if you want to publish the category when creating it.

  • category.category_unpublish Note: Only required if you want to unpublish the category when updating it.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
publishbooleanOptional

If 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:

  • true
  • false Note: To publish a category you need to have category.category_publish scope. Note: To unpublish a category you need to have category.category_unpublish scope.
Default: falseExample: true
Header parameters
Content-LanguagestringOptional

The 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) .
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
Body
parentIdstring | nullableOptional

Unique identifier of the parent category. No parentId in the body indicates that this is a root category.

ecnstring[] | nullableOptional

List of external category numbers (ECNs) unique for every category.

codestring | nullableOptional

Unique category identifier, defined by the tenant.

positioninteger · int32 | nullableOptional

Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.

publishedboolean | nullableOptional

Flag indicating whether the category has been published or not.

metadataall ofRequired
Responses
204
The category has been successfully updated
application/json
Responseobject
patch
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
  }
}
{}

Retrieving parents for a category

get

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_unpublished

    Note: Only required if the response should contain unpublished categories.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
showUnpublishedbooleanOptional

If set to true, not published categories are retrieved as well. Possible values:

  • true
  • false Note: To get unpublished categories you need to have category.category_read_unpublished scope.
Default: falseExample: true
pageNumberinteger · int32 · min: 1Optional

Page 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.

Default: 1
pageSizeinteger · int32 · min: 1Optional

Number of export files to be retrieved per page.

Default: 60
sortstringOptional

List 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.
Example: {fieldName}:ASC,{fieldName2}:DESC
Header parameters
Accept-LanguagestringOptional

List 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.
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
X-Total-CountbooleanOptional

The header value indicates if the total count of entities should be returned. Possible values:

  • true
  • false Default value: false
Default: falseExample: true
Responses
200
The request was successful. The category parents are returned.
application/json
get
GET /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-17T14:12:23.758Z",
      "to": "2025-07-17T14:12:23.758Z"
    },
    "position": 1,
    "published": true,
    "supercategoriesIds": [
      "text"
    ],
    "mixins": {},
    "Metadata": {
      "createdAt": "2025-07-17T14:12:23.758Z",
      "modifiedAt": "2025-07-17T14:12:23.758Z",
      "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"
        }
      }
    ]
  }
]

Retrieving subcategories for a category

get

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_unpublished

    Note: Only required if the response should contain unpublished categories.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
depthinteger · int32Optional

You 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

showUnpublishedbooleanOptional

If set to true, not published categories are retrieved as well. Possible values:

  • true
  • false Note: To get unpublished categories you need to have category.category_read_unpublished scope.
Default: falseExample: true
pageNumberinteger · int32 · min: 1Optional

Page 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.

Default: 1
pageSizeinteger · int32 · min: 1Optional

Number of export files to be retrieved per page.

Default: 60
sortstringOptional

List 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.
Example: {fieldName}:ASC,{fieldName2}:DESC
Header parameters
Accept-LanguagestringOptional

List 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.
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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]?$

Example: v2Pattern: ^v[1-9][0-9]?$
X-Total-CountbooleanOptional

The header value indicates if the total count of entities should be returned. Possible values:

  • true
  • false Default value: false
Default: falseExample: true
Responses
200
The request was successful. The category subcategories are returned.
application/json
get
GET /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-17T14:12:23.758Z",
      "to": "2025-07-17T14:12:23.758Z"
    },
    "position": 1,
    "published": true,
    "supercategoriesIds": [
      "text"
    ],
    "mixins": {},
    "Metadata": {
      "createdAt": "2025-07-17T14:12:23.758Z",
      "modifiedAt": "2025-07-17T14:12:23.758Z",
      "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?