Skip to main content

Categories API

Manage knowledge base categories. All endpoints require authentication.

Category object​

{
  "id": "e5f6a7b8-...",                            // UUID, auto-generated on create
  "identifier": "policies",                          // string, unique per instance
  "name": "Policies",                                // string, category name
  "description": "Store policies and legal info",    // string, category description
  "parentID": null,                                  // UUID or null, parent category ID
  "level": 0,                                        // integer, nesting level (0 for root)
  "visibility": "ALL",                               // string, visibility setting
  "sortOrder": 0,                                    // integer, sort order within parent
  "createdAt": "2025-01-15T10:30:00Z",              // datetime, creation timestamp
  "updatedAt": "2025-01-15T10:30:00Z"               // datetime, last update timestamp
}

List categories​

GET /api/kb/categories

Returns all categories for your instance.

Response:

{
  "success": true,
  "data": [
    {
      "id": "e5f6a7b8-...",
      "identifier": "policies",
      "name": "Policies",
      "description": "Store policies and legal information",
      "parentID": null,
      "level": 0,
      "visibility": "ALL",
      "sortOrder": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Get category​

GET /api/kb/categories/:id

Response:

{
  "success": true,
  "data": {
    "id": "e5f6a7b8-...",
    "identifier": "policies",
    "name": "Policies",
    "description": "Store policies and legal information",
    "parentID": null,
    "level": 0,
    "visibility": "ALL",
    "sortOrder": 0,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
}

Errors: 400 invalid id, 404 category not found.

Create category​

POST /api/kb/categories

Request body:

{
  "identifier": "policies",                        // required, unique identifier within instance
  "name": "Policies",                              // required, category name
  "description": "Store policies and legal info",  // optional, category description
  "parentID": null,                                // optional, parent category ID
  "level": 0,                                      // optional, nesting level
  "visibility": "ALL",                             // optional, visibility setting
  "sortOrder": 0                                   // optional, sort order
}

Response (status 201):

{
  "success": true,
  "data": {
    "id": "generated-uuid",
    "identifier": "policies",
    "name": "Policies",
    "description": "Store policies and legal info",
    "parentID": null,
    "level": 0,
    "visibility": "ALL",
    "sortOrder": 0,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
}

Update category​

PUT /api/kb/categories/:id

Request body: same as Create category.

Response (status 200): same structure as Create.

Errors: 400 invalid id, 404 category not found.

Delete category​

DELETE /api/kb/categories/:id
warning

Deleting a category also deletes all documents within that category.

Response:

{
  "success": true,
  "message": "deleted"
}

Errors: 400 invalid id.