Create a new folder - Welcome 👋

Overview

Create a new knowledge base folder to organize your documents. Folders help structure your AI assistant’s knowledge, making it easier to manage, update, and maintain your content. Folders can be nested to create hierarchical organizations that match your business structure.

Use Cases

Organize by Topic: Create folders for different product lines, services, or topics
Department Structure: Organize knowledge by department (Sales, Support, HR)
Content Type: Separate FAQs, policies, guides, and procedures
Nested Organization: Create parent folders with subfolders for detailed organization
Team Collaboration: Structure shared knowledge bases for team access
Version Control: Maintain different versions in separate folders

Authentication

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

x-api-key: your_api_key_here

Request Body

Field	Type	Required	Description
`name`	string	Yes	Folder name (must be unique per client)
`icon`	string	No	Emoji/icon for the folder
`sort_order`	number	No	Display order (default: 0)
`parent_folder_id`	string (UUID)	No	Parent folder ID for nested folders

Unique Names: Folder names must be unique within your organization.

Response Structure

Returns the created folder object:

Field	Type	Description
`id`	string (UUID)	Unique folder identifier
`name`	string	Folder name
`icon`	string \| null	Folder icon/emoji
`sort_order`	number	Display order
`client_id`	string (UUID)	Your organization ID
`parent_folder_id`	string \| null	Parent folder ID (null for root folders)
`created_at`	string (ISO)	Creation timestamp
`updated_at`	string (ISO)	Last update timestamp

Example Requests

Create Root Folder

curl --request POST \
  'https://api.vambe.ai/api/documents/assistant/folders' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "name": "Product Documentation",
    "icon": "📚",
    "sort_order": 0
  }'

Create Nested Folder

curl --request POST \
  'https://api.vambe.ai/api/documents/assistant/folders' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "name": "Advanced Features",
    "icon": "🚀",
    "parent_folder_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

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-09-30T10:00:00.000Z",
  "updated_at": "2024-09-30T10:00:00.000Z"
}

Common Use Cases

1. Create Folder Structure

const createFolderStructure = async () => {
  // Create main folder
  const mainFolder = await fetch(
    'https://api.vambe.ai/api/documents/assistant/folders',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        name: 'Support Documentation',
        icon: '📖',
      }),
    },
  ).then((r) => r.json());

  // Create subfolders
  const subfolder1 = await fetch(
    'https://api.vambe.ai/api/documents/assistant/folders',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        name: 'FAQs',
        icon: '❓',
        parent_folder_id: mainFolder.id,
      }),
    },
  ).then((r) => r.json());

  const subfolder2 = await fetch(
    'https://api.vambe.ai/api/documents/assistant/folders',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        name: 'Troubleshooting',
        icon: '🔧',
        parent_folder_id: mainFolder.id,
      }),
    },
  ).then((r) => r.json());

  console.log('Created folder structure:');
  console.log(`- ${mainFolder.name}`);
  console.log(`  - ${subfolder1.name}`);
  console.log(`  - ${subfolder2.name}`);

  return { mainFolder, subfolders: [subfolder1, subfolder2] };
};

2. Create Folder with Sort Order

const createOrderedFolders = async () => {
  const folderData = [
    { name: 'Getting Started', icon: '🚀', sort_order: 1 },
    { name: 'Advanced Topics', icon: '🎓', sort_order: 2 },
    { name: 'API Reference', icon: '📚', sort_order: 3 },
  ];

  const createdFolders = [];

  for (const data of folderData) {
    const folder = await fetch(
      'https://api.vambe.ai/api/documents/assistant/folders',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'your_api_key_here',
        },
        body: JSON.stringify(data),
      },
    ).then((r) => r.json());

    createdFolders.push(folder);
    console.log(`Created: ${folder.name} (order: ${folder.sort_order})`);
  }

  return createdFolders;
};

3. Create and Use Folder Immediately

const createFolderAndAddDocument = async (folderName, documentData) => {
  // 1. Create folder
  const folder = await fetch(
    'https://api.vambe.ai/api/documents/assistant/folders',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        name: folderName,
        icon: '📁',
      }),
    },
  ).then((r) => r.json());

  console.log(`Created folder: ${folder.name} (${folder.id})`);

  // 2. Upload document to the new folder
  const document = await fetch(
    'https://api.vambe.ai/api/documents/assistant/raw',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        content: documentData.content,
        fileName: documentData.fileName,
        externalId: documentData.externalId,
        folderId: folder.id, // Use newly created folder
        icon: '📄',
      }),
    },
  ).then((r) => r.json());

  console.log(`Added document: ${documentData.fileName}`);

  return { folder, document };
};

Sort Order

The sort_order field determines display order:

Lower numbers appear first
Default is 0 if not specified
Can be negative for priority items
Used for consistent UI ordering

Example:

{ name: 'Important', sort_order: -1 }  // Shows first
{ name: 'Main Docs', sort_order: 0 }   // Default position
{ name: 'Archive', sort_order: 10 }    // Shows last

Nested Folders

Create folder hierarchies by setting parent_folder_id:

// Level 1
const level1 = await createFolder({ name: 'Documentation', icon: '📚' });

// Level 2
const level2 = await createFolder({
  name: 'User Guides',
  icon: '📖',
  parent_folder_id: level1.id,
});

// Level 3
const level3 = await createFolder({
  name: 'Getting Started',
  icon: '🚀',
  parent_folder_id: level2.id,
});

Result: Documentation > User Guides > Getting Started

Error Responses

Status Code	Description
400	Bad Request - Invalid data or duplicate name
401	Unauthorized - Invalid or missing API key
500	Internal Server Error - Something went wrong

Important Notes

Unique Names: Folder names must be unique within your organization
UUID Parent: parent_folder_id must be a valid UUID of an existing folder
Icon Format: Icons are typically emoji characters (optional)
Sort Order: Use integers for consistent ordering
Auto-generated ID: Folder ID is automatically generated (UUID)

Folder Icons

Common folder icon examples:

Icon	Use Case
📚	General documentation
📁	Generic folder
🏢	Company/business folders
🛍️	Product folders
💡	Ideas/knowledge
🔧	Technical documentation
👥	Team/HR folders
📋	Policies/procedures
🎓	Training materials
🌐	Public/external content

GET /api/documents/assistant/folders - List all folders
POST /api/documents/assistant/raw - Upload document to folder
DELETE /api/documents/assistant/ - Delete a document

Workflow Example

Complete workflow for organizing knowledge base:

// 1. Create folder structure
const supportFolder = await createFolder({ name: 'Support', icon: '🆘' });
const faqFolder = await createFolder({
  name: 'FAQs',
  icon: '❓',
  parent_folder_id: supportFolder.id,
});

// 2. Upload documents to folders
await uploadDocument({
  folderId: faqFolder.id,
  content: 'Q: How to reset password?\nA: ...',
  fileName: 'password-reset.md',
});

// 3. List folders to verify
const allFolders = await getFolders();
console.log('Knowledge base organized!');

Headers

x-api-key

string

required

API key needed to authorize the request

Body

application/json

Folder details

name

string

required

Folder name

Example:

"Product Documentation"

icon

string

Optional icon/emoji for the folder

Example:

"📚"

sort_order

number

Optional sort order (default: 0)

Example:

0

parent_folder_id

string

Optional parent folder ID for nested folders

Example:

null

Response

Folder created successfully.

string

Example:

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

name

string

Example:

"Product Documentation"

icon

string

Example:

"📚"

sort_order

number

Example:

0

client_id

string

created_at

string

Example:

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

Knowledge Base

​Overview

​Use Cases

​Authentication

​Request Body

​Response Structure

​Example Requests

​Create Root Folder

​Create Nested Folder

​Example Response

​Common Use Cases

​1. Create Folder Structure

​2. Create Folder with Sort Order

​3. Create and Use Folder Immediately

​Sort Order

​Nested Folders

​Error Responses

​Important Notes

​Folder Icons

​Related Endpoints

​Workflow Example

Headers

Body

Response

Overview

Use Cases

Authentication

Request Body

Response Structure

Example Requests

Create Root Folder

Create Nested Folder

Example Response

Common Use Cases

1. Create Folder Structure

2. Create Folder with Sort Order

3. Create and Use Folder Immediately

Sort Order

Nested Folders

Error Responses

Important Notes

Folder Icons

Related Endpoints

Workflow Example