Get all folders

curl --request GET \
  --url https://api.vambe.me/api/documents/assistant/folders \
  --header 'x-api-key: <x-api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.vambe.me/api/documents/assistant/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Documentation",
    "icon": "📚",
    "sort_order": 0,
    "created_at": "2024-01-15T10:00:00.000Z",
    "documents": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "subfolders": [
      {}
    ]
  }
]

GET

api

documents

assistant

folders

Get all folders

curl --request GET \
  --url https://api.vambe.me/api/documents/assistant/folders \
  --header 'x-api-key: <x-api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.vambe.me/api/documents/assistant/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Documentation",
    "icon": "📚",
    "sort_order": 0,
    "created_at": "2024-01-15T10:00:00.000Z",
    "documents": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "subfolders": [
      {}
    ]
  }
]

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

curl --request GET \
  'https://api.vambe.me/api/documents/assistant/folders' \
  --header 'x-api-key: your_api_key_here'

Example Response

[
  {
    "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

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

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;
  }
};

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

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

POST /api/documents/assistant/folders - Create a new folder
POST /api/documents/assistant/raw - Upload document to folder
DELETE /api/documents/assistant/ - 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

Headers

x-api-key

string

required

API key needed to authorize the request

Response

Folders retrieved successfully.

string

Example:

"550e8400-e29b-41d4-a716-446655440000"

name

string

Example:

"Product Documentation"

icon

string

Example:

"📚"

sort_order

number

Example:

0

created_at

string

Example:

"2024-01-15T10:00:00.000Z"

documents

object[]

Show child attributes

subfolders

object[]

​Overview

​Use Cases

​Authentication

​Response Structure

​Folder Object

​Document Object (Simplified)

​Example Request

​Example Response

​Common Use Cases

​1. Display Folder Tree

​2. Find Folder by Name

​3. Build Folder Dropdown

​4. Count Total Documents

​Hierarchical Structure

​Error Responses

​Important Notes

​Related Endpoints

​Performance Tips

Headers

Response

Overview

Use Cases

Authentication

Response Structure

Folder Object

Document Object (Simplified)

Example Request

Example Response

Common Use Cases

1. Display Folder Tree

2. Find Folder by Name

3. Build Folder Dropdown

4. Count Total Documents

Hierarchical Structure

Error Responses

Important Notes

Related Endpoints

Performance Tips