Category Tree Resources

Read Category Trees

Deprecated

Retrieving a category tree

get

Retrieves a category tree.

Note: By default, only published categories are retrieved.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]{2,15}$

Responses

200

The request was successful. The category tree is returned.

application/json

idstringOptional

Category unique identifier generated when the category is created.

parentIdstringOptional

Unique identifier of the parent category.

nameone ofOptional

Category name.

stringOptional

Category name in the default language.

or

objectOptional

Map of translations. The keys should be ISO language codes. The values should be category names in specified languages.

codestringOptional

Unique category identifier, defined by the user.

descriptionone ofOptional

Category description.

stringOptional

Category description in the default language.

or

objectOptional

Map of translations. The keys should be ISO language codes. The values should be category descriptions in specified languages.

positionintegerOptional

Position in the category tree (on the same category level).

publishedbooleanOptional

Flag indicating whether the category has been published or not.

ecnstring[]Optional

List of external category numbers (ECNs).

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

The requested resource does not exist.

application/json

500

Some server-side error occurred. Details will be provided in the response payload.

application/json

get

/category/{tenant}/categories/categoryTree

HTTPcURLJavaScriptPython

GET /category/{tenant}/categories/categoryTree HTTP/1.1
Host: api.emporix.io
Accept: */*

{
  "id": "38118",
  "name": "ProductRoot",
  "code": "productroot",
  "description": "{\"type\":\"ProductRoot\"}",
  "position": 55555,
  "published": true,
  "subcategories": [
    {
      "id": "38119",
      "parentId": "38118",
      "name": "Fruits & Vegetables",
      "code": "fruits-&-vegetables",
      "description": "Fresh and tasty fruits and vegetables.",
      "position": 0,
      "published": true,
      "subcategories": [
        {
          "id": "38120",
          "parentId": "38119",
          "name": "Fruit",
          "code": "fruit",
          "position": 0,
          "published": true
        }
      ]
    }
  ]
}

Retrieving the category trees

get

Retrieves the category trees.

---

Additional scope info

• category.category_read_unpublished - Only required if the response should contain unpublished categories.

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Example: saasdev2

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

categoryIdsstring[]Optional

List of category IDs. If provided, the response returns only the category trees that include at least one of the specified categories.

Example: ["d9e4fdd0-e671-4968-9ba1-a5533a7f3b02","0f1056cc-b4b4-488b-9f95-245f6b542702"]

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

200

The request was successful. The category tree is returned.

application/json

Definition of category tree

idstringRequired

Category unique identifier generated when the category is created.

namestringRequiredDeprecated

Category name in tenant default language.

descriptionstringOptionalDeprecated

Description in tenant default language.

codestringOptionalDeprecated

Unique category identifier defined by the tenant.

positioninteger · int32Required

Category position in relation to sibling categories.

publishedbooleanRequired

Flag indicating whether the category has been published.

ecnstring[]Optional

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

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

application/json

get

/category/{tenant}/category-trees

HTTPcURLJavaScriptPython

GET /category/{tenant}/category-trees HTTP/1.1
Host: api.emporix.io
X-Version: v2
Accept: */*

[
  {
    "id": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
    "localizedName": {
      "en": "ProductRoot"
    },
    "code": "productroot",
    "localizedSlug": {
      "en": "productroot"
    },
    "localizedDescription": {
      "en": "ProductRoot"
    },
    "position": 55555,
    "published": true,
    "subcategories": [
      {
        "id": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
        "parentId": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
        "localizedName": {
          "en": "Fruits & Vegetables"
        },
        "code": "fruits-&-vegetables",
        "localizedSlug": {
          "en": "fruits-&-vegetables"
        },
        "localizedDescription": {
          "en": "Fresh and tasty fruits and vegetables."
        },
        "position": 0,
        "published": true,
        "subcategories": [
          {
            "id": "34a24ba108-e6fd-4139-b831-5ac5fded6dae",
            "parentId": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
            "localizedName": {
              "en": "Fruit"
            },
            "code": "fruit",
            "localizedSlug": {
              "en": "fruit"
            },
            "position": 0,
            "published": true
          }
        ]
      }
    ]
  }
]

Searching for category trees

post

Searches for category trees.

---

Additional scope info

• category.category_read_unpublished - Only required if the response should contain unpublished categories.

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Example: saasdev2

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

Content-LanguagestringOptional

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:

• * - 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).

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.

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

application/json

categoryIdsstring[]Required

List of category IDs. If provided, the response returns only the category trees that include at least one of the specified categories.

Responses

200

The request was successful. The category tree is returned.

application/json

Definition of category tree

idstringRequired

Category unique identifier generated when the category is created.

namestringRequiredDeprecated

Category name in tenant default language.

descriptionstringOptionalDeprecated

Description in tenant default language.

codestringOptionalDeprecated

Unique category identifier defined by the tenant.

positioninteger · int32Required

Category position in relation to sibling categories.

publishedbooleanRequired

Flag indicating whether the category has been published.

ecnstring[]Optional

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

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

post

/category/{tenant}/category-trees/search

HTTPcURLJavaScriptPython

POST /category/{tenant}/category-trees/search HTTP/1.1
Host: api.emporix.io
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "categoryIds": [
    "d9e4fdd0-e671-4968-9ba1-a5533a7f3b02",
    "0f1056cc-b4b4-488b-9f95-245f6b542702"
  ]
}

[
  {
    "id": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
    "localizedName": {
      "en": "ProductRoot"
    },
    "code": "productroot",
    "localizedSlug": {
      "en": "productroot"
    },
    "localizedDescription": {
      "en": "ProductRoot"
    },
    "position": 55555,
    "published": true,
    "subcategories": [
      {
        "id": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
        "parentId": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
        "localizedName": {
          "en": "Fruits & Vegetables"
        },
        "code": "fruits-&-vegetables",
        "localizedSlug": {
          "en": "fruits-&-vegetables"
        },
        "localizedDescription": {
          "en": "Fresh and tasty fruits and vegetables."
        },
        "position": 0,
        "published": true,
        "subcategories": [
          {
            "id": "34a24ba108-e6fd-4139-b831-5ac5fded6dae",
            "parentId": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
            "localizedName": {
              "en": "Fruit"
            },
            "code": "fruit",
            "localizedSlug": {
              "en": "fruit"
            },
            "position": 0,
            "published": true
          }
        ]
      }
    ]
  }
]

Retrieving a specific category tree

get

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.

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Example: saasdev2

categoryIdstringRequired

A unique identifier of a root category, generated when the category is created.

Example: 12a24ba108-e6fd-4139-b831-5ac5fded6d34

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

Content-LanguagestringOptional

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:

• * - 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).

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.

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 tree is returned.

application/json

Definition of category tree

idstringRequired

Category unique identifier generated when the category is created.

namestringRequiredDeprecated

Category name in tenant default language.

descriptionstringOptionalDeprecated

Description in tenant default language.

codestringOptionalDeprecated

Unique category identifier defined by the tenant.

positioninteger · int32Required

Category position in relation to sibling categories.

publishedbooleanRequired

Flag indicating whether the category has been published.

ecnstring[]Optional

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

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

application/json

404

Category tree with specified id does not exist

application/json

get

/category/{tenant}/category-trees/{categoryId}

HTTPcURLJavaScriptPython

GET /category/{tenant}/category-trees/{categoryId} HTTP/1.1
Host: api.emporix.io
X-Version: v2
Accept: */*

{
  "id": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
  "localizedName": {
    "en": "ProductRoot"
  },
  "code": "productroot",
  "localizedSlug": {
    "en": "productroot"
  },
  "localizedDescription": {
    "en": "ProductRoot"
  },
  "position": 55555,
  "published": true,
  "subcategories": [
    {
      "id": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
      "parentId": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
      "localizedName": {
        "en": "Fruits & Vegetables"
      },
      "code": "fruits-&-vegetables",
      "localizedSlug": {
        "en": "fruits-&-vegetables"
      },
      "localizedDescription": {
        "en": "Fresh and tasty fruits and vegetables."
      },
      "position": 0,
      "published": true,
      "subcategories": [
        {
          "id": "34a24ba108-e6fd-4139-b831-5ac5fded6dae",
          "parentId": "12a24ba108-e6fd-4139-b831-5ac5fded6d34",
          "localizedName": {
            "en": "Fruit"
          },
          "code": "fruit",
          "localizedSlug": {
            "en": "fruit"
          },
          "position": 0,
          "published": true
        }
      ]
    }
  ]
}