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, currently always "ALL" (reserved)
  "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",                        // unique identifier within instance
  "name": "Policies",                              // 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, currently always "ALL"
  "sortOrder": 0                                   // optional, sort order
}
Creating a category is not an upsert

Unlike a document, a category is always inserted. identifier is unique per instance, so posting an identifier that already exists fails instead of updating the existing category. List the categories first and use PUT on the one you already have.

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.

An update is a full replacement, not a patch

As with documents, the body replaces the stored category field by field, and a field you leave out is cleared rather than preserved. Send the whole object.

Delete category​

DELETE /api/kb/categories/:id
Deleting a category deletes its whole subtree

Deleting a category also deletes every document inside it, plus every child category with all of their documents. There is no undo.

Response:

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

Errors: 400 invalid id.