Skip to main content
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>'
[
  {
    "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": [
      {}
    ]
  }
]

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.

​
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

FieldTypeDescription
idstring (UUID)Unique folder identifier
namestringFolder name
iconstring | nullEmoji/icon for the folder
sort_ordernumberDisplay order (lower numbers first)
client_idstring (UUID)Your organization ID
parent_folder_idstring | nullParent folder ID (null for root folders)
source_urlstring | nullSource URL if synced from external source
source_typestring | nullType of source (e.g., ‘confluence’, ‘gdrive’)
is_publicbooleanWhether folder is publicly accessible
created_atstring (ISO)Folder creation timestamp
updated_atstring (ISO)Last update timestamp
documentsarrayArray of document objects in this folder
subfoldersarrayArray of nested folder objects

​
Document Object (Simplified)

FieldTypeDescription
idstring (UUID)Document identifier
namestringDocument name
iconstringDocument 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;
  }
};

​
3. Build Folder Dropdown

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 CodeDescription
401Unauthorized - Invalid or missing API key
500Internal 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

​
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.

​
id
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[]
​
subfolders
object[]