Document folders

Document folders let you organize knowledge base documents into logical groups. Each folder has a name, optional color, icon, and a position for display ordering.

Standard users can only manage their own folders. Admin users can manage folders for any user by passing adminMode: true and a userId.

List all folders

Retrieves all folders for the authenticated user with full folder fields including user_id and updated_at.

string

required

Must be "document-folders"

string

required

Must be "all"

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose folders to retrieve.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Folder UUID.

string

Folder name.

string

Hex color code.

string

Icon identifier.

number

Display order position.

string

Owner user ID.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

number

Total number of folders.

const response = await ApiService.invoke("document-folders", "all");

{
  "resource": "document-folders",
  "action": "all"
}

{
  "success": true,
  "data": {
    "folders": [
      {
        "id": "folder_123",
        "name": "Policies",
        "color": "#3B82F6",
        "icon": "folder",
        "position": 0,
        "user_id": "user_123",
        "created_at": "2026-02-19T10:00:00.000Z",
        "updated_at": "2026-02-19T10:00:00.000Z"
      }
    ],
    "count": 1
  }
}

List folders (compact)

Retrieves folders in a compact format optimized for dropdowns and select menus. Excludes user_id and updated_at.

string

required

Must be "document-folders"

string

required

Must be "list"

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose folders to retrieve.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Folder UUID.

string

Folder name.

string

Hex color code.

string

Icon identifier.

number

Display order position.

string

ISO 8601 creation timestamp.

number

Total number of folders.

const response = await ApiService.invoke("document-folders", "list");

{
  "resource": "document-folders",
  "action": "list"
}

{
  "success": true,
  "data": {
    "folders": [
      {
        "id": "folder_123",
        "name": "Policies",
        "color": "#3B82F6",
        "icon": "folder",
        "position": 0,
        "created_at": "2026-02-19T10:00:00.000Z"
      }
    ],
    "count": 1
  }
}

Get folder

Retrieves a single folder by ID.

string

required

Must be "document-folders"

string

required

Must be "get"

string

required

The folder UUID to retrieve.

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

boolean

Whether the request succeeded.

object

Show properties

object

Show properties

string

Folder UUID.

string

Folder name.

string

Hex color code.

string

Icon identifier.

number

Display order position.

string

Owner user ID.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

const response = await ApiService.invoke(
  "document-folders",
  "get",
  "folder_123"
);

{
  "resource": "document-folders",
  "action": "get",
  "id": "folder_123"
}

{
  "success": true,
  "data": {
    "folder": {
      "id": "folder_123",
      "name": "Policies",
      "color": "#3B82F6",
      "icon": "folder",
      "position": 0,
      "user_id": "user_123",
      "created_at": "2026-02-19T10:00:00.000Z",
      "updated_at": "2026-02-19T10:00:00.000Z"
    }
  }
}

Create folder

Creates a new document folder. The folder is automatically assigned the next available position.

string

required

Must be "document-folders"

string

required

Must be "create"

object

required

Show properties

string

required

Folder display name.

string

Hex color code for the folder (for example "#10B981").

string

Icon identifier (for example "folder", "briefcase").

string

Admin only. Create the folder for a specific user.

boolean

Whether the request succeeded.

object

Show properties

object

The newly created folder with all fields including auto-assigned position.

const response = await ApiService.invoke(
  "document-folders",
  "create",
  undefined,
  {
    name: "Training Materials",
    color: "#10B981",
    icon: "folder",
  }
);

curl -X POST https://api.helpgenie.ai/v1/document-folders \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "data": {
      "name": "Training Materials",
      "color": "#10B981",
      "icon": "folder"
    }
  }'

{
  "resource": "document-folders",
  "action": "create",
  "data": {
    "name": "Training Materials",
    "color": "#10B981",
    "icon": "folder"
  }
}

{
  "success": true,
  "data": {
    "folder": {
      "id": "folder_456",
      "name": "Training Materials",
      "color": "#10B981",
      "icon": "folder",
      "position": 1,
      "user_id": "user_123",
      "created_at": "2026-02-19T10:05:00.000Z",
      "updated_at": "2026-02-19T10:05:00.000Z"
    }
  }
}

Update folder

Updates an existing folder’s properties. Only the fields you provide are changed.

string

required

Must be "document-folders"

string

required

Must be "update"

string

required

The folder UUID to update.

object

required

Show properties

string

Updated folder name.

string

Updated hex color code.

string

Updated icon identifier.

number

Updated display position.

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user who owns the folder.

boolean

Whether the request succeeded.

object

Show properties

object

The updated folder with all current field values.

const response = await ApiService.invoke(
  "document-folders",
  "update",
  "folder_123",
  {
    name: "Company Policies",
    color: "#F59E0B",
    icon: "briefcase",
  }
);

{
  "resource": "document-folders",
  "action": "update",
  "id": "folder_123",
  "data": {
    "name": "Company Policies",
    "color": "#F59E0B",
    "icon": "briefcase"
  }
}

{
  "success": true,
  "data": {
    "folder": {
      "id": "folder_123",
      "name": "Company Policies",
      "color": "#F59E0B",
      "icon": "briefcase",
      "position": 0,
      "user_id": "user_123",
      "created_at": "2026-02-19T10:00:00.000Z",
      "updated_at": "2026-02-19T10:10:00.000Z"
    }
  }
}

Delete folder

Permanently deletes a folder. Documents in the folder are not deleted; they become uncategorized.

When a folder is deleted, any documents inside it are unlinked, not deleted. Their folder_id is set to null, making them appear as uncategorized in the knowledge base. You do not need to manually move documents before deleting a folder.

string

required

Must be "document-folders"

string

required

Must be "delete"

string

required

The folder UUID to delete.

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user who owns the folder.

boolean

Whether the request succeeded.

object

Show properties

boolean

Operation succeeded.

string

Confirmation message.

const response = await ApiService.invoke(
  "document-folders",
  "delete",
  "folder_123"
);

{
  "resource": "document-folders",
  "action": "delete",
  "id": "folder_123"
}

{
  "success": true,
  "data": {
    "success": true,
    "message": "Folder deleted successfully"
  }
}

Reorder folders

Updates the display order of folders based on an ordered array of folder IDs. The position of each folder is set to its index in the array.

string

required

Must be "document-folders"

string

required

Must be "reorder"

object

required

Show properties

string[]

required

Ordered array of folder UUIDs. The first ID gets position 0, the second gets position 1, and so on.

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose folders to reorder.

boolean

Whether the request succeeded.

object

Show properties

boolean

Operation succeeded.

string

Confirmation message.

const response = await ApiService.invoke(
  "document-folders",
  "reorder",
  undefined,
  {
    folderIds: ["folder_456", "folder_123", "folder_789"],
  }
);

{
  "resource": "document-folders",
  "action": "reorder",
  "data": {
    "folderIds": ["folder_456", "folder_123", "folder_789"]
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "message": "Folders reordered successfully"
  }
}

Get folder document counts

Returns the number of documents in each folder. Useful for displaying counts in folder lists without fetching all documents.

string

required

Must be "document-folders"

string

required

Must be "counts"

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose folder counts to retrieve.

boolean

Whether the request succeeded.

object

Show properties

object

An object where keys are folder IDs and values are document counts.

const response = await ApiService.invoke("document-folders", "counts");

{
  "resource": "document-folders",
  "action": "counts"
}

{
  "success": true,
  "data": {
    "counts": {
      "folder_123": 5,
      "folder_456": 2
    }
  }
}

Error codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`FORBIDDEN`	403	Only admins can manage folders for other users
`NOT_FOUND`	404	Folder not found
`VALIDATION_ERROR`	400	Missing or invalid parameters (for example folder ID required)
`INTERNAL_ERROR`	500	Server-side error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List all folders

List folders (compact)

Get folder

Create folder

Update folder

Delete folder

Reorder folders

Get folder document counts

Error codes

​List all folders

​List folders (compact)

​Get folder

​Create folder

​Update folder

​Delete folder

​Reorder folders

​Get folder document counts

​Error codes

List all folders

List folders (compact)

Get folder

Create folder

Update folder

Delete folder

Reorder folders

Get folder document counts

Error codes