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

# Get all folders

> Retrieve all knowledge base folders for your organization.

## Overview

Retrieve all knowledge base folders for your organization. Folders help organize documents used by your AI assistants, making it easy to manage and structure your knowledge base.

This endpoint returns a hierarchical structure of folders with their associated documents and subfolders.

## Use Cases

* **Folder Selection**: Display available folders when uploading documents
* **Knowledge Base Browser**: Build a file explorer interface
* **Organization Overview**: See how your knowledge base is structured
* **Document Count**: Understand content distribution across folders
* **Assistant Configuration**: Show folders linked to specific assistants

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Response Structure

Returns an array of folder objects with hierarchical structure:

### Folder Object

| Field              | Type           | Description                                   |
| ------------------ | -------------- | --------------------------------------------- |
| `id`               | string (UUID)  | Unique folder identifier                      |
| `name`             | string         | Folder name                                   |
| `icon`             | string \| null | Emoji/icon for the folder                     |
| `sort_order`       | number         | Display order (lower numbers first)           |
| `client_id`        | string (UUID)  | Your organization ID                          |
| `parent_folder_id` | string \| null | Parent folder ID (null for root folders)      |
| `source_url`       | string \| null | Source URL if synced from external source     |
| `source_type`      | string \| null | Type of source (e.g., 'confluence', 'gdrive') |
| `is_public`        | boolean        | Whether folder is publicly accessible         |
| `created_at`       | string (ISO)   | Folder creation timestamp                     |
| `updated_at`       | string (ISO)   | Last update timestamp                         |
| `documents`        | array          | Array of document objects in this folder      |
| `subfolders`       | array          | Array of nested folder objects                |

### Document Object (Simplified)

| Field  | Type          | Description         |
| ------ | ------------- | ------------------- |
| `id`   | string (UUID) | Document identifier |
| `name` | string        | Document name       |
| `icon` | string        | Document icon/emoji |

## Example Request

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/documents/assistant/folders' \
  --header 'x-api-key: your_api_key_here'
```

## Example Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Documentation",
    "icon": "📚",
    "sort_order": 0,
    "client_id": "660e8400-e29b-41d4-a716-446655440001",
    "parent_folder_id": null,
    "source_url": null,
    "source_type": null,
    "is_public": false,
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z",
    "documents": [
      {
        "id": "doc-001",
        "name": "Getting Started Guide",
        "icon": "📄"
      },
      {
        "id": "doc-002",
        "name": "API Reference",
        "icon": "📋"
      }
    ],
    "subfolders": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Advanced Features",
        "icon": "🚀",
        "sort_order": 0,
        "client_id": "660e8400-e29b-41d4-a716-446655440001",
        "parent_folder_id": "550e8400-e29b-41d4-a716-446655440000",
        "source_url": null,
        "source_type": null,
        "is_public": false,
        "created_at": "2024-02-01T10:00:00.000Z",
        "updated_at": "2024-02-01T10:00:00.000Z",
        "documents": [],
        "subfolders": []
      }
    ]
  },
  {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "name": "Company Policies",
    "icon": "📋",
    "sort_order": 1,
    "client_id": "660e8400-e29b-41d4-a716-446655440001",
    "parent_folder_id": null,
    "source_url": null,
    "source_type": null,
    "is_public": false,
    "created_at": "2024-01-20T10:00:00.000Z",
    "updated_at": "2024-01-20T10:00:00.000Z",
    "documents": [
      {
        "id": "doc-003",
        "name": "Privacy Policy",
        "icon": "🔒"
      }
    ],
    "subfolders": []
  }
]
```

## Common Use Cases

### 1. Display Folder Tree

```javascript theme={null}
const displayFolderTree = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/documents/assistant/folders',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const folders = await response.json();

  const renderFolder = (folder, indent = 0) => {
    const spaces = '  '.repeat(indent);
    console.log(
      `${spaces}${folder.icon || '📁'} ${folder.name} (${folder.documents.length} docs)`,
    );

    folder.documents.forEach((doc) => {
      console.log(`${spaces}  ${doc.icon} ${doc.name}`);
    });

    folder.subfolders.forEach((subfolder) => {
      renderFolder(subfolder, indent + 1);
    });
  };

  folders.forEach((folder) => renderFolder(folder));

  return folders;
};
```

### 2. Find Folder by Name

```javascript theme={null}
const findFolderByName = async (folderName) => {
  const response = await fetch(
    'https://api.vambe.me/api/documents/assistant/folders',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const folders = await response.json();

  const findRecursive = (folders, name) => {
    for (const folder of folders) {
      if (folder.name.toLowerCase() === name.toLowerCase()) {
        return folder;
      }
      if (folder.subfolders.length > 0) {
        const found = findRecursive(folder.subfolders, name);
        if (found) return found;
      }
    }
    return null;
  };

  const folder = findRecursive(folders, folderName);

  if (folder) {
    console.log(`Found folder: ${folder.name} (ID: ${folder.id})`);
    console.log(`Contains ${folder.documents.length} documents`);
    return folder;
  } else {
    console.log(`Folder "${folderName}" not found`);
    return null;
  }
};
```

### 3. Build Folder Dropdown

```javascript theme={null}
const buildFolderDropdown = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/documents/assistant/folders',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const folders = await response.json();

  const flattenFolders = (folders, prefix = '') => {
    let result = [];

    folders.forEach((folder) => {
      result.push({
        value: folder.id,
        label: `${prefix}${folder.icon || '📁'} ${folder.name}`,
        documentCount: folder.documents.length,
      });

      if (folder.subfolders.length > 0) {
        result = result.concat(
          flattenFolders(folder.subfolders, `${prefix}  `),
        );
      }
    });

    return result;
  };

  const options = flattenFolders(folders);

  return options;
};

// Use in a select component
// <Select options={options} placeholder="Select a folder..." />
```

### 4. Count Total Documents

```javascript theme={null}
const countTotalDocuments = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/documents/assistant/folders',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const folders = await response.json();

  const countRecursive = (folders) => {
    return folders.reduce((total, folder) => {
      return (
        total + folder.documents.length + countRecursive(folder.subfolders)
      );
    }, 0);
  };

  const totalDocs = countRecursive(folders);

  console.log(`Total documents across all folders: ${totalDocs}`);

  return totalDocs;
};
```

## Hierarchical Structure

Folders are organized hierarchically:

* **Root Folders**: Have `parent_folder_id: null`
* **Subfolders**: Have `parent_folder_id` pointing to parent
* **Nesting**: Unlimited depth of nested folders
* **Documents**: Each folder has `documents` array

## Error Responses

| Status Code | Description                                  |
| ----------- | -------------------------------------------- |
| 401         | Unauthorized - Invalid or missing API key    |
| 500         | Internal Server Error - Something went wrong |

## Important Notes

* **Hierarchical**: Response includes full folder tree with nesting
* **Document Summary**: Only includes document id, name, and icon (not full content)
* **Alphabetical**: Folders typically sorted alphabetically
* **No Pagination**: Returns all folders in one request
* **Empty Folders**: Folders with no documents still appear

## Related Endpoints

* [POST /api/documents/assistant/folders](/reference/assistant/create-folder) - Create a new folder
* [POST /api/documents/assistant/raw](/reference/assistant/upload-document) - Upload document to folder
* [DELETE /api/documents/assistant/{externalId}](/reference/assistant/delete-document) - Delete a document

## Performance Tips

* **Cache Response**: Folder structure changes infrequently
* **Client-side Filtering**: Filter and search folders on client side
* **Lazy Loading**: For large folder trees, consider lazy loading subfolders


## OpenAPI

````yaml get /api/documents/assistant/folders
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/documents/assistant/folders:
    get:
      tags:
        - Assistant Documents
      summary: Get all folders
      description: Retrieve all knowledge base folders for your organization.
      operationId: PublicRagieController_getFolders
      parameters:
        - name: x-api-key
          in: header
          description: API key needed to authorize the request
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Folders retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: 550e8400-e29b-41d4-a716-446655440000
                    name:
                      type: string
                      example: Product Documentation
                    icon:
                      type: string
                      example: 📚
                    sort_order:
                      type: number
                      example: 0
                    created_at:
                      type: string
                      example: '2024-01-15T10:00:00.000Z'
                    documents:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                    subfolders:
                      type: array
                      items:
                        type: object
        '401':
          description: Unauthorized.

````