Upload Images

POST /api/upload

Uploads one or more images to the photo frame collection. Requires admin authentication.

This is a protected endpoint. You must be logged in as admin to upload images.

Request

file[]

required

One or more image files to upload

string

Target folder path. If not specified, uploads to root directory.

Request Example

Single File

curl -X POST http://localhost:3000/api/upload \
  -H "Cookie: session-cookie" \
  -F "files=@photo1.jpg"

Multiple Files with Folder

curl -X POST http://localhost:3000/api/upload \
  -H "Cookie: session-cookie" \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.png" \
  -F "folder=vacation/2023"

Response

{
  "success": true,
  "message": "3 files uploaded successfully",
  "data": {
    "uploadedFiles": [
      {
        "originalName": "photo1.jpg",
        "fileName": "photo1.jpg",
        "path": "vacation/2023/photo1.jpg",
        "size": 2048576,
        "mimeType": "image/jpeg"
      },
      {
        "originalName": "photo2.png", 
        "fileName": "photo2.png",
        "path": "vacation/2023/photo2.png",
        "size": 1536000,
        "mimeType": "image/png"
      }
    ],
    "folder": "vacation/2023",
    "totalFiles": 2,
    "totalSize": 3584576
  }
}

{
  "success": false,
  "error": "File too large",
  "code": "FILE_SIZE_EXCEEDED",
  "details": {
    "maxSize": "10MB",
    "fileSize": "15MB",
    "fileName": "large-photo.jpg"
  }
}

File Restrictions

Limit

Maximum 10MB per file (configurable via MAX_FILE_SIZE env var)

Allowed

JPEG, PNG, GIF, WebP images only

Limit

No hard limit, but large batches may timeout

Status Codes

Success

Files uploaded successfully

Bad Request

Invalid file format or missing files

Unauthorized

Admin authentication required

Payload Too Large

File size exceeds maximum limit

Server Error

Upload processing or file system error

JavaScript Example

async function uploadImages(files, folder = '') {
  const formData = new FormData();
  
  // Add files to form data
  files.forEach(file => {
    formData.append('files', file);
  });
  
  // Add folder if specified
  if (folder) {
    formData.append('folder', folder);
  }
  
  try {
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
      credentials: 'include' // Include session cookie
    });
    
    const result = await response.json();
    
    if (result.success) {
      console.log(`Uploaded ${result.data.totalFiles} files`);
      return result.data.uploadedFiles;
    } else {
      throw new Error(result.error);
    }
  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

// Usage with file input
const fileInput = document.getElementById('file-input');
fileInput.addEventListener('change', async (e) => {
  const files = Array.from(e.target.files);
  await uploadImages(files, 'new-photos');
});

Folder Creation

Target folders are created automatically if they don’t exist
Nested folder paths are supported (e.g., vacation/2023/summer)
Use forward slashes for folder separators
Folder names cannot contain special characters: < > : " | ? * \

REST API

Authentication

Photos API

Folders API

POST /api/upload

Request

Request Example

Response

File Restrictions

Status Codes

JavaScript Example

Folder Creation

​POST /api/upload

​Request

​Request Example

​Response

​File Restrictions

​Status Codes

​JavaScript Example

​Folder Creation

POST /api/upload

Request

Request Example

Response

File Restrictions

Status Codes

JavaScript Example

Folder Creation