Create Folder

POST /api/folders

Creates a new folder in the photo frame collection. Requires admin authentication.

This is a protected endpoint. You must be logged in as admin to create folders.

Request

string

required

Full path for the new folder (relative to uploads directory)

string

required

Folder name (used for the final directory in the path)

Request Examples

Root Level Folder

curl -X POST http://localhost:3000/api/folders \
  -H "Content-Type: application/json" \
  -H "Cookie: session-cookie" \
  -d '{"path": "new-album", "name": "new-album"}'

Nested Folder

curl -X POST http://localhost:3000/api/folders \
  -H "Content-Type: application/json" \
  -H "Cookie: session-cookie" \
  -d '{"path": "vacation/2024/spring", "name": "spring"}'

Response

{
  "success": true,
  "message": "Folder created successfully",
  "data": {
    "folderPath": "vacation/2024/spring",
    "folderName": "spring",
    "parentPath": "vacation/2024",
    "created": "2023-08-15T10:30:00Z",
    "exists": false
  }
}

{
  "success": true,
  "message": "Folder already exists",
  "data": {
    "folderPath": "vacation/2023",
    "folderName": "2023", 
    "parentPath": "vacation",
    "created": "2023-01-15T08:20:00Z",
    "exists": true
  }
}

{
  "success": false,
  "error": "Invalid folder name contains prohibited characters",
  "code": "INVALID_FOLDER_NAME",
  "details": {
    "prohibitedChars": ["<", ">", ":", "\"", "|", "?", "*", "\\"]
  }
}

Response Fields

string

Full path to the created/existing folder

string

Name of the folder

string

Path to the parent directory

string

ISO timestamp when folder was created

boolean

Whether the folder already existed before this request

Status Codes

Success

Folder created successfully or already exists

Bad Request

Invalid folder name or path format

Unauthorized

Admin authentication required

Server Error

File system error during folder creation

Folder Name Rules

Folder names cannot contain these characters: < > : " | ? * \

Valid Characters:

Letters (a-z, A-Z)
Numbers (0-9)
Spaces
Hyphens (-)
Underscores (_)
Periods (.)

Naming Guidelines:

Use descriptive names
Avoid very long names (keep under 100 characters)
Consider sorting (use dates, numbers for chronological order)

JavaScript Example

async function createFolder(folderPath, folderName) {
  try {
    const response = await fetch('/api/folders', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      credentials: 'include', // Include session cookie
      body: JSON.stringify({
        path: folderPath,
        name: folderName
      })
    });
    
    const result = await response.json();
    
    if (result.success) {
      if (result.data.exists) {
        console.log('Folder already exists:', result.data.folderPath);
      } else {
        console.log('Folder created:', result.data.folderPath);
      }
      return result.data;
    } else {
      throw new Error(result.error);
    }
  } catch (error) {
    console.error('Folder creation failed:', error);
    throw error;
  }
}

// Usage examples
createFolder('events/2024', '2024')
  .then(folder => {
    console.log('Ready to upload to:', folder.folderPath);
  });

createFolder('backup/old-photos', 'old-photos')
  .then(folder => {
    console.log('Backup folder ready:', folder.folderPath);
  });

Nested Folder Creation

The API automatically creates parent directories if they don’t exist:

// This will create all necessary parent folders:
// - events/
// - events/2024/
// - events/2024/wedding/
// - events/2024/wedding/ceremony/
createFolder('events/2024/wedding/ceremony', 'ceremony');

Best Practices

Organization: Use consistent naming schemes (dates, categories)
Hierarchy: Create logical folder structures (year/month, event/location)
Planning: Create folders before uploading related images
Validation: Check folder names before creation to avoid errors

REST API

Authentication

Photos API

Folders API

POST /api/folders

Request

Request Examples

Response

Response Fields

Status Codes

Folder Name Rules

JavaScript Example

Nested Folder Creation

Best Practices

​POST /api/folders

​Request

​Request Examples

​Response

​Response Fields

​Status Codes

​Folder Name Rules

​JavaScript Example

​Nested Folder Creation

​Best Practices

POST /api/folders

Request

Request Examples

Response

Response Fields

Status Codes

Folder Name Rules

JavaScript Example

Nested Folder Creation

Best Practices