> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Document folders

> Organize knowledge base documents into 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.

> [!NOTE]
>
> 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`.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"all"`

**data** `object`

**properties**

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user whose folders to retrieve.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**folders** `array`

**item properties**

**id** `string`

Folder UUID.

**name** `string`

Folder name.

**color** `string`

Hex color code.

**icon** `string`

Icon identifier.

**position** `number`

Display order position.

**user\_id** `string`

Owner user ID.

**created\_at** `string`

ISO 8601 creation timestamp.

**updated\_at** `string`

ISO 8601 last-updated timestamp.

**count** `number`

Total number of folders.

```typescript ApiService.invoke() theme={null}
const response = await ApiService.invoke("document-folders", "all");
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "all"
}
```

```json Response theme={null}
{
  "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`.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"list"`

**data** `object`

**properties**

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user whose folders to retrieve.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**folders** `array`

**item properties**

**id** `string`

Folder UUID.

**name** `string`

Folder name.

**color** `string`

Hex color code.

**icon** `string`

Icon identifier.

**position** `number`

Display order position.

**created\_at** `string`

ISO 8601 creation timestamp.

**count** `number`

Total number of folders.

```typescript ApiService.invoke() theme={null}
const response = await ApiService.invoke("document-folders", "list");
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "list"
}
```

```json Response theme={null}
{
  "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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"get"`

**id** `string` *required*

The folder UUID to retrieve.

**data** `object`

**properties**

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**folder** `object`

**properties**

**id** `string`

Folder UUID.

**name** `string`

Folder name.

**color** `string`

Hex color code.

**icon** `string`

Icon identifier.

**position** `number`

Display order position.

**user\_id** `string`

Owner user ID.

**created\_at** `string`

ISO 8601 creation timestamp.

**updated\_at** `string`

ISO 8601 last-updated timestamp.

```typescript ApiService.invoke() theme={null}
const response = await ApiService.invoke(
  "document-folders",
  "get",
  "folder_123"
);
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "get",
  "id": "folder_123"
}
```

```json Response theme={null}
{
  "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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"create"`

**data** `object` *required*

**properties**

**name** `string` *required*

Folder display name.

**color** `string`

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

**icon** `string`

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

**userId** `string`

Admin only. Create the folder for a specific user.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**folder** `object`

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

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

```bash cURL theme={null}
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"
    }
  }'
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "create",
  "data": {
    "name": "Training Materials",
    "color": "#10B981",
    "icon": "folder"
  }
}
```

```json Response theme={null}
{
  "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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"update"`

**id** `string` *required*

The folder UUID to update.

**data** `object` *required*

**properties**

**name** `string`

Updated folder name.

**color** `string`

Updated hex color code.

**icon** `string`

Updated icon identifier.

**position** `number`

Updated display position.

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user who owns the folder.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**folder** `object`

The updated folder with all current field values.

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

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "update",
  "id": "folder_123",
  "data": {
    "name": "Company Policies",
    "color": "#F59E0B",
    "icon": "briefcase"
  }
}
```

```json Response theme={null}
{
  "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.

> [!NOTE]
>
> 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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"delete"`

**id** `string` *required*

The folder UUID to delete.

**data** `object`

**properties**

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user who owns the folder.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**success** `boolean`

Operation succeeded.

**message** `string`

Confirmation message.

```typescript ApiService.invoke() theme={null}
const response = await ApiService.invoke(
  "document-folders",
  "delete",
  "folder_123"
);
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "delete",
  "id": "folder_123"
}
```

```json Response theme={null}
{
  "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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"reorder"`

**data** `object` *required*

**properties**

**folderIds** `string[]` *required*

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

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user whose folders to reorder.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**success** `boolean`

Operation succeeded.

**message** `string`

Confirmation message.

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

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "reorder",
  "data": {
    "folderIds": ["folder_456", "folder_123", "folder_789"]
  }
}
```

```json Response theme={null}
{
  "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.

**resource** `string` *required*

Must be `"document-folders"`

**action** `string` *required*

Must be `"counts"`

**data** `object`

**properties**

**adminMode** `boolean` (default: false)

Admin only. Enables cross-user access.

**userId** `string`

Admin only. Target user whose folder counts to retrieve.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**counts** `object`

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

```typescript ApiService.invoke() theme={null}
const response = await ApiService.invoke("document-folders", "counts");
```

```json Request body theme={null}
{
  "resource": "document-folders",
  "action": "counts"
}
```

```json Response theme={null}
{
  "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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.