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

# Create a new folder

> Create a new knowledge base folder to organize documents.

## 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     |

<Note>
  **Unique Names**: Folder names must be unique within your organization.
</Note>

## 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

```bash theme={null}
curl --request POST \
  'https://api.vambe.me/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

```bash theme={null}
curl --request POST \
  'https://api.vambe.me/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

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

## Common Use Cases

### 1. Create Folder Structure

```javascript theme={null}
const createFolderStructure = async () => {
  // Create main folder
  const mainFolder = await fetch(
    'https://api.vambe.me/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.me/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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
const createFolderAndAddDocument = async (folderName, documentData) => {
  // 1. Create folder
  const folder = await fetch(
    'https://api.vambe.me/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.me/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:

```javascript theme={null}
{ 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`:

```javascript theme={null}
// 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  |

## Related Endpoints

* [GET /api/documents/assistant/folders](/reference/assistant/get-folders) - List all folders
* [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

## Workflow Example

Complete workflow for organizing knowledge base:

```javascript theme={null}
// 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!');
```


## OpenAPI

````yaml post /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:
    post:
      tags:
        - Assistant Documents
      summary: Create a new folder
      description: Create a new knowledge base folder to organize documents.
      operationId: PublicRagieController_createFolder
      parameters:
        - name: x-api-key
          in: header
          description: API key needed to authorize the request
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: Folder details
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Folder name
                  example: Product Documentation
                icon:
                  type: string
                  description: Optional icon/emoji for the folder
                  example: 📚
                sort_order:
                  type: number
                  description: 'Optional sort order (default: 0)'
                  example: 0
                parent_folder_id:
                  type: string
                  description: Optional parent folder ID for nested folders
                  example: null
              required:
                - name
      responses:
        '201':
          description: Folder created successfully.
          content:
            application/json:
              schema:
                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
                  client_id:
                    type: string
                  created_at:
                    type: string
                    example: '2024-01-15T10:00:00.000Z'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.

````