List Knowledge Base Categories

GET /categories - List Knowledge Base Categories

Retrieve a list of all categories in the knowledge base with their content in different languages. This endpoint is useful for understanding the current category structure, synchronization, and preparing for category imports.

Endpoint

GET /v1/knowledge-base/categories

Request Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes

Response Format

Success Response (200 OK)

{
  "categories": [
    {
      "id": 123,
      "correlationId": "docs-category",
      "parentCategoryId": null,
      "order": 1,
      "isFeatured": true,
      "icon": "image-guid-123",
      "contents": [
        {
          "lang": "en",
          "title": "Documentation",
          "description": "All documentation and guides",
          "slug": "docs",
          "slug_state": "manual"
        },
        {
          "lang": "es",
          "title": "Documentación",
          "description": "Toda la documentación y guías",
          "slug": "documentacion",
          "slug_state": "auto"
        }
      ]
    },
    {
      "id": 124,
      "correlationId": "getting-started",
      "parentCategoryId": 123,
      "order": 1,
      "isFeatured": false,
      "icon": null,
      "contents": [
        {
          "lang": "en",
          "title": "Getting Started",
          "description": "Beginner guides and tutorials",
          "slug": "getting-started",
          "slug_state": "auto"
        }
      ]
    }
  ]
}

Response Fields

Category Object (`categories[]`)

Field	Type	Description	Example
`id`	`number`	Internal database ID of the category	`123`
`correlationId`	`string`	Custom correlation ID (if set)	`"docs-category"`
`parentCategoryId`	`number`	Parent category ID (null for root categories)	`null`
`order`	`number`	Display order within parent category	`1`
`isFeatured`	`boolean`	Whether category is featured	`true`
`icon`	`string`	Category icon (emoji or text)	`"📚"`
`contents`	`array`	Category content in different languages	See Content Object below

Content Object (`contents[]`)

Field	Type	Description	Example
`lang`	`string`	Language code (ISO 639-1)	`"en"`
`title`	`string`	Category title	`"Documentation"`
`description`	`string`	Category description	`"All documentation and guides"`
`slug`	`string`	URL slug	`"docs"`
`slug_state`	`string`	Slug generation mode: "auto" or "manual"	`"manual"`

Common Use Cases

This endpoint fetches the complete category tree with parent-child relationships. The structure supports one level of hierarchy:

Root categories: Have parentCategoryId: null
Child categories: Have parentCategoryId pointing to their parent category ID

Correlation ID Usage

The correlationId field serves as an external identifier that articles use during import to reference categories. When importing articles, you can specify a category by its correlationId instead of the internal database ID, making it easier to maintain relationships across different systems.

Use this endpoint to understand your current category structure and relationships before making changes or imports.

Common Error Scenarios

HTTP Error Codes

401 Unauthorized: Invalid or missing API token
500 Internal Server Error: Server-side processing error

Error Response Examples

401 Unauthorized

{
  "error": "AuthenticationMissing",
  "message": "Missing token"
}

500 Internal Server Error

{
  "error": "Internal server error occurred while retrieving categories"
}

Rate Limiting

Check out this guide for detailed information about API limits and optimization strategies.

Usage Examples

Example 1: Get All Categories

curl -X GET "https://api.productfruits.com/v1/knowledgebase/categories" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "categories": [
    {
      "id": 1,
      "correlationId": "documentation",
      "parentCategoryId": null,
      "order": 1,
      "isFeatured": true,
      "icon": "image-guid-123",
      "contents": [
        {
          "lang": "en",
          "title": "Documentation",
          "description": "Complete documentation and guides",
          "slug": "docs",
          "slug_state": "manual"
        }
      ]
    }
  ]
}