List Folders

GET /api/folders

Returns the folder structure and contents for slideshow navigation and admin management.

Parameters

string

Specific folder path to get contents from. If not provided, returns root level structure.

Request Examples

Root Structure

curl http://localhost:3000/api/folders

Specific Folder

curl "http://localhost:3000/api/folders?path=vacation/2023"

Response

{
  "success": true,
  "data": {
    "currentPath": "",
    "folders": [
      {
        "name": "vacation",
        "path": "vacation",
        "imageCount": 45,
        "subfolderCount": 3,
        "lastModified": "2023-07-20T15:30:00Z"
      },
      {
        "name": "family-photos",
        "path": "family-photos", 
        "imageCount": 128,
        "subfolderCount": 5,
        "lastModified": "2023-06-15T09:20:00Z"
      }
    ],
    "images": [
      {
        "name": "welcome.jpg",
        "path": "welcome.jpg",
        "size": 2048576,
        "lastModified": "2023-05-01T12:00:00Z",
        "dimensions": {
          "width": 1920,
          "height": 1080
        }
      }
    ],
    "totalFolders": 2,
    "totalImages": 1
  }
}

{
  "success": true,
  "data": {
    "currentPath": "vacation/2023",
    "parentPath": "vacation",
    "folders": [
      {
        "name": "summer",
        "path": "vacation/2023/summer",
        "imageCount": 23,
        "subfolderCount": 0,
        "lastModified": "2023-07-15T14:20:00Z"
      },
      {
        "name": "winter",
        "path": "vacation/2023/winter",
        "imageCount": 18,
        "subfolderCount": 0,
        "lastModified": "2023-02-28T10:45:00Z"
      }
    ],
    "images": [
      {
        "name": "beach-sunset.jpg",
        "path": "vacation/2023/beach-sunset.jpg",
        "size": 3145728,
        "lastModified": "2023-07-10T18:30:00Z",
        "dimensions": {
          "width": 2560,
          "height": 1440
        }
      }
    ],
    "totalFolders": 2,
    "totalImages": 1
  }
}

Response Fields

string

Current folder path being viewed

string

Path to parent folder (null for root level)

array

Array of subfolders in current directory

array

Array of images in current directory

number

Count of subfolders in current directory

number

Count of images in current directory

Folder Object

string

Folder display name

string

Full path to folder from root

number

Number of images in this folder (recursive)

number

Number of direct subfolders

string

ISO timestamp of last modification

Image Object

string

Image filename

string

Full path to image from root

number

File size in bytes

object

Image width and height in pixels

string

ISO timestamp of last modification

Status Codes

Success

Folder contents retrieved successfully

Not Found

Specified folder path does not exist

Server Error

Error accessing file system

Usage Example

async function loadFolderContents(folderPath = '') {
  try {
    const url = folderPath 
      ? `/api/folders?path=${encodeURIComponent(folderPath)}`
      : '/api/folders';
      
    const response = await fetch(url);
    const data = await response.json();
    
    if (data.success) {
      return {
        folders: data.data.folders,
        images: data.data.images,
        currentPath: data.data.currentPath,
        parentPath: data.data.parentPath
      };
    } else {
      throw new Error(data.error);
    }
  } catch (error) {
    console.error('Failed to load folder:', error);
    throw error;
  }
}

// Build folder navigation
function buildFolderTree() {
  loadFolderContents()
    .then(data => {
      data.folders.forEach(folder => {
        console.log(`${folder.name}: ${folder.imageCount} images`);
      });
    })
    .catch(error => {
      console.error('Navigation failed:', error);
    });
}

Path Handling

Use forward slashes for folder separators
Paths are relative to the uploads directory
URL encode folder names with special characters
Empty path parameter returns root level
Invalid paths return 404 error

REST API

Authentication

Photos API

Folders API

GET /api/folders

Parameters

Request Examples

Response

Response Fields

Folder Object

Image Object

Status Codes

Usage Example

Path Handling

​GET /api/folders

​Parameters

​Request Examples

​Response

​Response Fields

​Folder Object

​Image Object

​Status Codes

​Usage Example

​Path Handling

GET /api/folders

Parameters

Request Examples

Response

Response Fields

Folder Object

Image Object

Status Codes

Usage Example

Path Handling