Create a Category

Customers see categories as the sections of the help center home page and as category pages. Admins manage them in the knowledge base settings. Every knowledge base starts with a hidden root category (root: true), which Kustomer creates along with the knowledge base. Top-level categories are children of the root, and categories nest through parent. An article joins a category through the article's own categories list, so one article can appear in several categories, even in different knowledge bases.

Placement in the tree

A category always belongs to the same knowledge base as its parent, and its knowledgeBase is set from the parent. If you create a category without parent, it goes under the root of the org's default knowledge base. To add a category to another knowledge base, set parent to that knowledge base's root category or to a category inside it. Kustomer rejects a parent in a different knowledge base, a category as its own parent, and any parent for a root category.

Key fields

• langs holds the text for each language, keyed by language code (for example en_us): title, slug, description and disabled. If you leave out slug, Kustomer builds it from title.
• hash is the short ID in the category's URL, as in /categories/shipping-rJ5Dz7bLL. Kustomer generates it unless you send one.
• positions is the ordered list of article IDs in the category, and categoryPositions is the ordered list of its subcategories. Both set display order. Kustomer adds an article to positions when the article joins the category, so you only need to send these fields to reorder.
• icon is the image shown with the category, and externalId is your own unique ID for syncing from another system.

Send deleted: true to PUT /v1/kb/categories/{id} to soft-delete a category. You can't delete a root category. Deleting a category doesn't change its articles, so update any article that still lists it in categories.

Public and internal categories

The /p/v3 category endpoints serve the help center. They need no API key and return each category's text flattened for the requested lang. Like the other public knowledge base endpoints, they work out the knowledge base from the host, so call your org host for the default knowledge base. Fetching a category by ID with includeChildren=true also returns its published articles and child categories in included. childrenLimit caps the number of child categories. includeRoot adds the root category to the list.

Internal categories are a separate, org-wide tree for organizing internal content. They don't belong to any knowledge base, and the public endpoints never return them. Listing them returns every internal category except the root.

Which endpoint to use

Called with an API key, GET /v1/kb/categories returns only categories that hold a published public article, plus the categories above them, and leaves out the default knowledge base's root. A new or empty category doesn't appear there until it has content, so keep the IDs you create and read them by ID. externalId and hash must be unique in the org, so Kustomer rejects a duplicate. Reads need a knowledge base read role, and writes need org.admin.kb.write or the matching permission.