### Build and Start Production App

Source: https://foldergram.github.io/installation

Use these commands to build the server and client for production and then start the application. This process does not build the documentation site.

```bash
pnpm build
pnpm start
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://foldergram.github.io/quick-start

Run these commands to install project dependencies, set up the environment file, and start the development server. The Vite client runs on port 4141, the Express server on 4140, and the VitePress docs on 4145.

```bash
pnpm install
cp .env.example .env
pnpm dev
```

--------------------------------

### Gallery Indexing Structure Examples

Source: https://foldergram.github.io/troubleshooting

Examples of folder structures that are ignored versus indexed by Foldergram.

```text
gallery/
  loose-file.jpg
  trips/
    oslo/
      notes.txt
```

```text
gallery/
  trips/
    oslo/
      IMG_0001.jpg
```

--------------------------------

### Create Foldergram Directory

Source: https://foldergram.github.io/installation

Initialize the working directory for the installation.

```bash
mkdir foldergram
cd foldergram
```

--------------------------------

### Foldergram Directory Layout

Source: https://foldergram.github.io/installation

Expected directory structure after initial setup.

```text
foldergram/
  docker-compose.yml
  data/
    gallery/
      example-album/
```

--------------------------------

### GET /api/folders

Source: https://foldergram.github.io/api

Returns a list of folder summaries.

```APIDOC
## GET /api/folders

### Description
Returns a list of folder summaries.

### Method
GET

### Endpoint
/api/folders

### Response
#### Success Response (200)
- **items** (array) - List of folder objects containing id, slug, name, description, folderPath, breadcrumb, imageCount, videoCount, latestImageMtimeMs, hasAvatarStory, avatarImageId, and avatarUrl.
```

--------------------------------

### Build and start from source

Source: https://foldergram.github.io/quick-start

Use this command if you have cloned the repository and wish to build the images locally.

```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build
```

--------------------------------

### GET /api/likes

Source: https://foldergram.github.io/api

Returns a list of likes.

```APIDOC
## GET /api/likes

### Description
Returns a list of likes ordered by timestamp descending.

### Method
GET

### Endpoint
/api/likes

### Response
#### Success Response (200)
- **items** (array) - List of likes
```

--------------------------------

### Start Foldergram container

Source: https://foldergram.github.io/quick-start

Launch the application using the default Docker Compose configuration.

```bash
docker compose up -d
```

--------------------------------

### GET /api/originals/:id

Source: https://foldergram.github.io/api

Serves the original media file from disk.

```APIDOC
## GET /api/originals/:id

### Description
Serves the original file associated with the given ID. Can be streamed inline or downloaded as an attachment.

### Method
GET

### Endpoint
/api/originals/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the media item.

#### Query Parameters
- **download** (number) - Optional - Set to '1' to trigger a file download attachment.

### Response
#### Error Response (404)
- **message** (string) - "Original media not found"
```

--------------------------------

### GET /api/status

Source: https://foldergram.github.io/api

Returns the operational state of the application.

```APIDOC
## GET /api/status

### Description
Returns a viewer-safe operational state including indexed counts, scan progress, and configuration preferences.

### Method
GET

### Endpoint
/api/status

### Response
#### Success Response (200)
- **folders** (array) - Active indexed folders.
- **indexedImages** (number) - Total count of indexed posts.
- **indexedVideos** (number) - Total count of indexed videos.
- **scan** (object) - Viewer-safe scan progress snapshot.
- **storage** (object) - Storage availability status.
- **libraryIndex** (object) - Rebuild requirements.
- **preferences** (object) - App-wide configuration settings.
```

--------------------------------

### GET /api/folders/:slug

Source: https://foldergram.github.io/api

Returns a single folder summary by slug.

```APIDOC
## GET /api/folders/:slug

### Description
Returns one folder summary.

### Method
GET

### Endpoint
/api/folders/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The folder slug

### Response
#### Error Response (404)
- **message** (string) - Folder not found
```

--------------------------------

### POST /api/admin/rescan

Source: https://foldergram.github.io/api

Initiates a manual scan of the current library and starts the development watcher.

```APIDOC
## POST /api/admin/rescan

### Description
Runs a manual scan against the current library and then starts the development watcher.

### Method
POST

### Endpoint
/api/admin/rescan

### Request Body
(No request body specified)

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **lastScan** (object) - Information about the last scan performed.
  - **id** (integer) - The ID of the scan run.
  - **status** (string) - The status of the scan (e.g., "completed").
  - **scanned_files** (integer) - The number of files scanned.

#### Response Example
```json
{
  "ok": true,
  "lastScan": {
    "id": 7,
    "status": "completed",
    "scanned_files": 120
  }
}
```

### Errors
- **409** - Library-rebuild-required message when the gallery root changed.
- **403** - For viewer sessions.
- **500** - For scan failures surfaced from the scanner.
```

--------------------------------

### GET /api/admin/scan-progress

Source: https://foldergram.github.io/api

Returns detailed administrative scan progress information.

```APIDOC
## GET /api/admin/scan-progress

### Description
Provides a detailed scan progress report for administrators, including specific file paths and full error logs.

### Method
GET

### Endpoint
/api/admin/scan-progress

### Response
#### Success Response (200)
- **currentFile** (string) - The file currently being processed.
- **currentFolder** (string) - The folder currently being processed.
- **lastCompletedScan** (object) - Full scan record including error_text.
```

--------------------------------

### Docker Compose and Project Management Commands

Source: https://foldergram.github.io/quick-start

A collection of essential commands for managing the Foldergram project using Docker and pnpm. This includes starting/stopping Docker services, rescanning data, running tests, building the project and documentation, and starting the application.

```bash
docker compose up -d
```

```bash
docker compose down
```

```bash
pnpm rescan
```

```bash
pnpm test
```

```bash
pnpm build
```

```bash
pnpm start
```

```bash
pnpm build:docs
```

--------------------------------

### Success Response for Image Like

Source: https://foldergram.github.io/api

Example JSON response indicating a successful like operation on an image.

```json
{
  "ok": true,
  "id": 42,
  "liked": true
}
```

--------------------------------

### GET /api/scan-progress

Source: https://foldergram.github.io/api

Returns a lightweight, viewer-safe scan progress report.

```APIDOC
## GET /api/scan-progress

### Description
Provides a viewer-safe snapshot of the current scan or rebuild process for UI polling.

### Method
GET

### Endpoint
/api/scan-progress

### Response
#### Success Response (200)
- **isScanning** (boolean) - Scan status.
- **phase** (string) - Current scan phase (idle, migration, discovery, derivatives).
- **scanReason** (string) - Trigger for the current scan.
- **currentPhaseMessage** (string) - UI summary of the phase.
- **currentOperation** (string) - Current action label.
```

--------------------------------

### Success Response for Folder Deletion

Source: https://foldergram.github.io/api

Example JSON response indicating a successful deletion of a folder, including counts of deleted items.

```json
{
  "ok": true,
  "slug": "oslo",
  "deletedImageCount": 12,
  "deletedFolderCount": 1,
  "deletedSourceFolder": false
}
```

--------------------------------

### GET /api/folders/:slug/stories

Source: https://foldergram.github.io/api

Returns the stories payload for a folder.

```APIDOC
## GET /api/folders/:slug/stories

### Description
Returns the stories payload for one folder.

### Method
GET

### Endpoint
/api/folders/:slug/stories

### Parameters
#### Path Parameters
- **slug** (string) - Required - The folder slug

### Response
#### Success Response (200)
- **railKind** (string) - Type of rail
- **railTitle** (string) - Title of the rail
- **items** (array) - List of stories
- **highlights** (array) - List of highlights
```

--------------------------------

### Success Response for Admin Rescan

Source: https://foldergram.github.io/api

Example JSON response for a successful manual library rescan operation.

```json
{
  "ok": true,
  "lastScan": {
    "id": 7,
    "status": "completed",
    "scanned_files": 120
  }
}
```

--------------------------------

### GET /api/folders/:slug/images

Source: https://foldergram.github.io/api

Returns images for a specific folder.

```APIDOC
## GET /api/folders/:slug/images

### Description
Returns images for a specific folder.

### Method
GET

### Endpoint
/api/folders/:slug/images

### Parameters
#### Path Parameters
- **slug** (string) - Required - The folder slug

#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (default: 24, max: 60)
- **mediaType** (string) - Optional - Filter by image or video

### Response
#### Success Response (200)
- **folder** (object) - Folder details
- **items** (array) - List of media items
- **page** (integer) - Current page
- **limit** (integer) - Items per page
- **total** (integer) - Total items
- **hasMore** (boolean) - Whether more items exist
```

--------------------------------

### GET /api/feed/moments

Source: https://foldergram.github.io/api

Retrieves the current Home Moments or Highlights definition.

```APIDOC
## GET /api/feed/moments

### Description
Returns the current Home Moments or Highlights definition.

### Method
GET

### Endpoint
/api/feed/moments

### Response
#### Success Response (200)
- **railKind** (string) - The type of rail (moments or highlights)
- **railTitle** (string) - Title of the rail
- **railDescription** (string) - Description of the rail
- **railSingularLabel** (string) - Singular label for items
- **items** (array) - List of items

#### Response Example
{
  "railKind": "moments",
  "railTitle": "Moments",
  "railDescription": "Memory capsules shaped by real capture dates from your library.",
  "railSingularLabel": "Moment",
  "items": []
}
```

--------------------------------

### Rescan Library

Source: https://foldergram.github.io/api

Manually triggers a scan of the current library and starts the development watcher. Useful after external changes to the library.

```http
POST /api/admin/rescan
```

--------------------------------

### GET /api/folders/:slug/stories/:id

Source: https://foldergram.github.io/api

Returns a specific story capsule for a folder.

```APIDOC
## GET /api/folders/:slug/stories/:id

### Description
Returns the stories payload for one folder.

### Method
GET

### Endpoint
/api/folders/:slug/stories/:id

### Parameters
#### Path Parameters
- **slug** (string) - Required - The folder slug
- **id** (string) - Required - The story ID

#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (default: 24)

### Response
#### Success Response (200)
- **story** (object) - Story details
- **items** (array) - Paginated feed items
```

--------------------------------

### Success Response for Image Deletion

Source: https://foldergram.github.io/api

Example JSON response indicating a successful deletion of an image.

```json
{
  "ok": true,
  "id": 42,
  "folderSlug": "oslo"
}
```

--------------------------------

### GET /api/auth/status

Source: https://foldergram.github.io/api

Returns the current authentication state for the browser session, including role and capabilities.

```APIDOC
## GET /api/auth/status

Returns the current auth state for the browser session.

### Response Example

```json
{
  "enabled": true,
  "authenticated": false,
  "role": "anonymous",
  "accessMode": "public",
  "likesMode": "local",
  "capabilities": {
    "canManageLibrary": false,
    "canDeleteMedia": false,
    "canAccessSettings": false,
    "canUseSharedLikes": false,
    "canUseLocalFavorites": true
  }
}
```
```

--------------------------------

### GET /api/health Response Shape

Source: https://foldergram.github.io/api

Returns the current process health and storage status.

```json
{
  "ok": true,
  "timestamp": "2026-03-16T12:34:56.000Z",
  "storage": {
    "available": true,
    "reason": null,
    "usingInMemoryDatabase": false
  }
}
```

--------------------------------

### GET /api/feed Response Shape

Source: https://foldergram.github.io/api

Returns a paginated list of media items.

```json
{
  "mode": "recent",
  "items": [],
  "page": 1,
  "limit": 24,
  "total": 0,
  "hasMore": false
}
```

--------------------------------

### GET /api/reels Response Shape

Source: https://foldergram.github.io/api

Returns a paginated list of video items.

```json
{
  "mode": "recommended",
  "items": [],
  "page": 1,
  "limit": 6,
  "total": 0,
  "hasMore": false
}
```

--------------------------------

### GET /api/health

Source: https://foldergram.github.io/api

Retrieves the process-level health status and storage state of the Foldergram application.

```APIDOC
## GET /api/health

Returns process-level health plus storage state.

### Response Example

```json
{
  "ok": true,
  "timestamp": "2026-03-16T12:34:56.000Z",
  "storage": {
    "available": true,
    "reason": null,
    "usingInMemoryDatabase": false
  }
}
```
```

--------------------------------

### GET /api/images/:id

Source: https://foldergram.github.io/api

Retrieves detailed information about a specific image or video post.

```APIDOC
## GET /api/images/:id

### Description
Retrieves a detailed payload for a specific media item, including metadata and navigation IDs for the current folder.

### Method
GET

### Endpoint
/api/images/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the media item.

#### Query Parameters
- **mediaType** (string) - Optional - Filter by 'image' or 'video'.

### Response
#### Success Response (200)
- **feed-item fields** (object) - Standard feed item metadata.
- **relativePath** (string) - Path relative to gallery root.
- **mimeType** (string) - Media MIME type.
- **fileSize** (number) - Size of the file.
- **originalUrl** (string) - URL to the original file.
- **playbackStrategy** (string) - Strategy for video playback.
- **nextImageId** (string) - ID of the next item.
- **previousImageId** (string) - ID of the previous item.

#### Error Response (404)
- **message** (string) - "Post not found"
```

--------------------------------

### GET /api/reels

Source: https://foldergram.github.io/api

Retrieves video items for reels, supporting pagination, various modes, and navigation hints.

```APIDOC
## GET /api/reels

Query parameters:

| Param        | Type    | Default | Notes                                                                                                |
|--------------|---------|---------|------------------------------------------------------------------------------------------------------|
| `page`       | integer | `1`     | Minimum `1`.                                                                                         |
| `limit`      | integer | `24`    | Minimum `1`, maximum `60`. The current client helper requests `6` per page.                            |
| `mode`       | string  |         | `recommended| recent| random`                                                                         |
| `seed`       | integer | unset   | Optional seed used to keep `recommended` and `random` queues stable while paging.                    |
| `lastFolder` | string  | unset   | Optional recent-navigation hint used by `recommended`.                                               |
| `recentFolders`| string  | unset   | Optional recent-navigation hints used by `recommended`.                                              |

Response shape:

```json
{
  "mode": "recommended",
  "items": [],
  "page": 1,
  "limit": 6,
  "total": 0,
  "hasMore": false
}
```

Notes:

* `items` contain videos only.
* `recommended` uses `lastFolder` and `recentFolders` to bias the queue toward folders you recently opened.
* `recent` ignores recommendation hints and returns newest indexed videos first.
* `random` and `recommended` stay stable across pages when the same `seed` is reused.
```

--------------------------------

### GET /api/feed

Source: https://foldergram.github.io/api

Retrieves items for the feed, supporting pagination and different sorting modes.

```APIDOC
## GET /api/feed

Query parameters:

| Param | Type    | Default | Notes                                  |
|-------|---------|---------|----------------------------------------|
| `page`  | integer | `1`     | Minimum `1`.                           |
| `limit` | integer | `24`    | Minimum `1`, maximum `60`.             |
| `mode`  | string  |         | `recent| rediscover| random`           |
| `seed`  | integer | unset   | Optional random seed for `random` mode.|

Response shape:

```json
{
  "mode": "recent",
  "items": [],
  "page": 1,
  "limit": 24,
  "total": 0,
  "hasMore": false
}
```

Notes:

* `items` contain both images and videos.
* `thumbnailUrl` points to `/thumbnails/...`.
* `previewUrl` points to `/previews/...`.
```

--------------------------------

### GET /api/auth/status Response Shape

Source: https://foldergram.github.io/api

Returns the current authentication state and user capabilities for the session.

```json
{
  "enabled": true,
  "authenticated": false,
  "role": "anonymous",
  "accessMode": "public",
  "likesMode": "local",
  "capabilities": {
    "canManageLibrary": false,
    "canDeleteMedia": false,
    "canAccessSettings": false,
    "canUseSharedLikes": false,
    "canUseLocalFavorites": true
  }
}
```

--------------------------------

### GET /api/admin/stats

Source: https://foldergram.github.io/api

Retrieves the full admin operational payload, including storage and library index details.

```APIDOC
## GET /api/admin/stats

### Description
Returns the full admin operational payload. This route is read-only but admin-only.

### Method
GET

### Endpoint
/api/admin/stats

### Response
#### Success Response (200)
- **deletedImages** (number) - Soft-deleted post count.
- **thumbnailCount** (number) - Actual generated thumbnail files currently present on disk.
- **previewCount** (number) - Actual generated preview files currently present on disk.
- **storage.usingInMemoryDatabase** (boolean) - Whether SQLite had to fall back to in-memory mode.
- **libraryIndex.currentGalleryRoot** (string) - Current configured gallery root.
- **libraryIndex.previousGalleryRoot** (string) - Prior configured gallery root when the root changed.
- **libraryIndex.lastSuccessfulGalleryRoot** (string) - Gallery root from the last completed successful scan.
- **lastScan** (string) - Last completed scan run.
```

--------------------------------

### Create Gallery Directory

Source: https://foldergram.github.io/installation

Set up the initial directory structure for media storage.

```bash
mkdir -p data/gallery/example-album
```

--------------------------------

### Build Documentation

Source: https://foldergram.github.io/troubleshooting

Command to build the project documentation.

```bash
pnpm build:docs
```

--------------------------------

### Run Development Servers

Source: https://foldergram.github.io/installation

These commands are used to run the development versions of the server, client, and documentation site independently.

```bash
pnpm dev:server
```

```bash
pnpm dev:client
```

```bash
pnpm dev:docs
```

--------------------------------

### Download Docker Compose File

Source: https://foldergram.github.io/installation

Fetch the official Docker Compose configuration file.

```bash
wget -O docker-compose.yml https://raw.githubusercontent.com/foldergram/foldergram/main/docker-compose.yml
```

--------------------------------

### Define local data directory structure

Source: https://foldergram.github.io/quick-start

Create these directories on your host machine to map them into the Foldergram container.

```text
data/
  gallery/
  db/
  thumbnails/
  previews/
```

--------------------------------

### GET /api/feed/moments/:id

Source: https://foldergram.github.io/api

Retrieves a specific moment capsule by ID.

```APIDOC
## GET /api/feed/moments/:id

### Description
Retrieves a specific moment capsule by ID.

### Method
GET

### Endpoint
/api/feed/moments/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the moment capsule

#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (default: 24)

### Response
#### Error Response (404)
- **message** (string) - Feed capsule not found
```

--------------------------------

### Configure Foldergram environment variables

Source: https://foldergram.github.io/configuration

Use this .env configuration to define runtime settings such as ports, data paths, and concurrency limits.

```bash
NODE_ENV=development
SERVER_PORT=4141
DEV_SERVER_PORT=4140
DEV_CLIENT_PORT=4141
DATA_ROOT=./data
GALLERY_ROOT=./data/gallery
GALLERY_EXCLUDED_FOLDERS=
DB_DIR=./data/db
THUMBNAILS_DIR=./data/thumbnails
PREVIEWS_DIR=./data/previews
IMAGE_DETAIL_SOURCE=preview
DERIVATIVE_MODE=eager
LOG_VERBOSE=0
SCAN_DISCOVERY_CONCURRENCY=4
SCAN_DERIVATIVE_CONCURRENCY=4
PUBLIC_DEMO_MODE=0
CSRF_TRUSTED_ORIGINS=
```

--------------------------------

### Configure folder stories and highlights

Source: https://foldergram.github.io/quick-start

Use a reserved stories/ folder to define folder avatars and highlight capsules.

```text
data/
  gallery/
    AnimalPlanet/
      post-1.jpg
      stories/
        story-1.mp4
        story-2.jpg
        Lions/
          clip-1.mp4
          nested-1/
            clip-2.jpg
```

--------------------------------

### Configure Stories Mode via PUT /api/admin/settings/stories-mode

Source: https://foldergram.github.io/api

Sets how folders named 'stories' are interpreted by the application.

```json
{
  "treatStoriesAsFolders": false
}
```

```json
{
  "treatStoriesAsFolders": false
}
```

--------------------------------

### Define gallery structure expectations

Source: https://foldergram.github.io/configuration

Foldergram indexes folders containing media; files placed directly in the root or non-media files are ignored.

```text
gallery/
  loose-file.jpg         # ignored
  trips/
    oslo/
      IMG_0001.jpg       # indexed folder
    berlin/
      notes.txt          # not indexed
```

--------------------------------

### PUT /api/admin/settings/stories-mode

Source: https://foldergram.github.io/api

Configures how 'stories' folders are interpreted.

```APIDOC
## PUT /api/admin/settings/stories-mode

### Description
Sets how folders literally named 'stories' are interpreted.

### Method
PUT

### Endpoint
/api/admin/settings/stories-mode

### Request Body
- **treatStoriesAsFolders** (boolean) - Required - If false, enables reserved-stories mode.
```

--------------------------------

### POST /api/auth/login

Source: https://foldergram.github.io/api

Authenticates a user with a password.

```APIDOC
## POST /api/auth/login

### Description
Authenticates the user using an admin or viewer password.

### Method
POST

### Endpoint
/api/auth/login

### Request Body
- **password** (string) - Required - The admin or viewer password.

### Request Example
{
  "password": "your-admin-or-viewer-password"
}

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the request.
- **auth** (object) - Authentication details including role and capabilities.
```

--------------------------------

### POST /api/admin/rebuild-index

Source: https://foldergram.github.io/api

Stops the watcher, clears and rebuilds the indexed library, then restarts the watcher.

```APIDOC
## POST /api/admin/rebuild-index

### Description
Stops the watcher, clears the indexed library tables, rescans the current gallery root, and then restarts the watcher. This resets `likes`, `images`, `folders`, `folder_scan_state`, and `scan_runs`. Cached derivatives are left in place.

### Method
POST

### Endpoint
/api/admin/rebuild-index

### Request Body
(No request body specified)

### Response
(No success response specified)
```

--------------------------------

### Structure stories and highlights

Source: https://foldergram.github.io/configuration

Foldergram treats 'stories' folders specially by default, allowing for nested media organization.

```text
gallery/
  AnimalPlanet/
    post-1.jpg          # indexed owner folder media
    stories/
      story-1.mp4       # avatar story set
      Lions/
        clip-1.mp4      # highlight capsule
        nested-1/
          clip-2.jpg    # still part of Lions
```

--------------------------------

### PUT /api/auth/viewer-access

Source: https://foldergram.github.io/api

Configures viewer access mode.

```APIDOC
## PUT /api/auth/viewer-access

### Description
Configures viewer access mode (off, password, or public).

### Method
PUT

### Endpoint
/api/auth/viewer-access

### Request Body
- **mode** (string) - Required - Access mode (off, password, public).
- **viewerPassword** (string) - Optional - Required if mode is password.
```

--------------------------------

### Set Home Feed Default via PUT /api/admin/settings/home-feed-default

Source: https://foldergram.github.io/api

Configures the default mode for the Home feed.

```json
{
  "defaultMode": "recent"
}
```

```json
{
  "defaultMode": "recent"
}
```

--------------------------------

### Organize media in gallery folder

Source: https://foldergram.github.io/quick-start

Foldergram indexes albums based on folders containing media files. Nested folders are treated as separate albums.

```text
data/
  gallery/
    trips/
      oslo/
        IMG_0001.jpg
        clip-01.mp4
    family/
      summer-2024/
        porch.webp
```

--------------------------------

### POST /api/admin/rebuild-thumbnails

Source: https://foldergram.github.io/api

Stops the watcher, clears the thumbnail cache, regenerates thumbnails and video poster images, and restarts the watcher.

```APIDOC
## POST /api/admin/rebuild-thumbnails

### Description
Stops the watcher, clears the thumbnail cache, regenerates thumbnails and video poster images from indexed media, and restarts the watcher. This does not reset previews, likes, folder records, or scan history.

### Method
POST

### Endpoint
/api/admin/rebuild-thumbnails

### Request Body
(No request body specified)

### Response
(No success response specified)

### Errors
- **409** - Library-rebuild-required message when a library-index rebuild is required.
- **403** - For viewer sessions.
```

--------------------------------

### Configure lazy derivative generation

Source: https://foldergram.github.io/quick-start

Set these environment variables in docker-compose.yml to reduce upfront processing time for large libraries.

```env
IMAGE_DETAIL_SOURCE=original
DERIVATIVE_MODE=lazy
```

--------------------------------

### POST /api/images/:id/like

Source: https://foldergram.github.io/api

Marks a specific image as liked. Returns the updated like status.

```APIDOC
## POST /api/images/:id/like

### Description
Marks a post as liked.

### Method
POST

### Endpoint
/api/images/:id/like

### Request Body
(No request body specified)

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **id** (integer) - The ID of the image that was liked.
- **liked** (boolean) - The new like status of the image (true).

#### Response Example
```json
{
  "ok": true,
  "id": 42,
  "liked": true
}
```

### Errors
- **404** - Image not found when the post does not exist or is deleted.
- **403** - When trust requirements are missing.
```

--------------------------------

### PUT /api/admin/settings/home-feed-default

Source: https://foldergram.github.io/api

Sets the default mode for the Home feed.

```APIDOC
## PUT /api/admin/settings/home-feed-default

### Description
Sets the default mode used when Home opens.

### Method
PUT

### Endpoint
/api/admin/settings/home-feed-default

### Request Body
- **defaultMode** (string) - Required - Allowed values: recent, rediscover, random.
```

--------------------------------

### Authenticate User via POST /api/auth/login

Source: https://foldergram.github.io/api

Authenticates a user session. Requires a password if protection is enabled.

```json
{
  "password": "your-admin-or-viewer-password"
}
```

```json
{
  "ok": true,
  "auth": {
    "enabled": true,
    "authenticated": true,
    "role": "viewer",
    "accessMode": "password",
    "likesMode": "shared",
    "capabilities": {
      "canManageLibrary": false,
      "canDeleteMedia": false,
      "canAccessSettings": false,
      "canUseSharedLikes": true,
      "canUseLocalFavorites": false
    }
  }
}
```

--------------------------------

### Configure Viewer Access via PUT /api/auth/viewer-access

Source: https://foldergram.github.io/api

Sets the viewer access mode to off, password-protected, or public.

```json
{
  "mode": "off"
}
```

```json
{
  "mode": "password",
  "viewerPassword": "viewer-password"
}
```

--------------------------------

### Mark Image as Liked

Source: https://foldergram.github.io/api

Use this endpoint to mark a specific image as liked. Returns the updated like status.

```http
POST /api/images/:id/like
```

--------------------------------

### Elevate to Admin Session via POST /api/auth/unlock-admin

Source: https://foldergram.github.io/api

Elevates a current session to admin status by verifying the admin password.

```json
{
  "password": "your-admin-password"
}
```

```json
{
  "ok": true,
  "auth": {
    "enabled": true,
    "authenticated": true,
    "role": "admin",
    "accessMode": "public",
    "likesMode": "shared",
    "capabilities": {
      "canManageLibrary": true,
      "canDeleteMedia": true,
      "canAccessSettings": true,
      "canUseSharedLikes": true,
      "canUseLocalFavorites": false
    }
  }
}
```

--------------------------------

### POST /api/auth/unlock-admin

Source: https://foldergram.github.io/api

Elevates the current session to admin status.

```APIDOC
## POST /api/auth/unlock-admin

### Description
Elevates the current browser into an admin session by verifying the admin password.

### Method
POST

### Endpoint
/api/auth/unlock-admin

### Request Body
- **password** (string) - Required - The admin password.

### Request Example
{
  "password": "your-admin-password"
}
```

--------------------------------

### Rebuild Thumbnails

Source: https://foldergram.github.io/api

Stops the watcher, clears the thumbnail cache, regenerates thumbnails and video poster images, and restarts the watcher. Does not affect previews or other metadata.

```http
POST /api/admin/rebuild-thumbnails
```

--------------------------------

### Manage Admin Password via PUT /api/auth/password

Source: https://foldergram.github.io/api

Sets or changes the admin password. Requires current password if protection is already enabled.

```json
{
  "password": "new-password"
}
```

```json
{
  "currentPassword": "old-password",
  "password": "new-password"
}
```

--------------------------------

### Foldergram Mutation Requirements

Source: https://foldergram.github.io/api

All mutating API routes are protected by `requireTrustedMutationRequest`, which enforces specific header and origin checks.

```APIDOC
## Mutation Requirements

All mutating API routes are protected by `requireTrustedMutationRequest`.

### Required Header

```http
x-foldergram-intent: 1
```

### Local-Origin Checks

For mutating requests:

* If `Origin` is present, it must be `localhost`, `127.0.0.1`, or `::1`.
* In development and test, the origin port must match `DEV_SERVER_PORT` or the reserved dev-client range from `DEV_CLIENT_PORT` through `DEV_CLIENT_PORT + 3`.
* In production, loopback origins are allowed and same-host origins are allowed when they match the host serving the app on `SERVER_PORT`.
* If `Origin` is absent but `Referer` is present, the same loopback check is applied to the referer origin.

The shipped frontend adds `x-foldergram-intent: 1` automatically for `POST`, `PUT`, `PATCH`, and `DELETE` requests.
```

--------------------------------

### API Endpoints for Status and Scan Progress

Source: https://foldergram.github.io/configuration

These endpoints provide information about the current status of the Foldergram service and the progress of library scans.

```APIDOC
## GET /api/status

### Description
Retrieves the current viewer-safe scan snapshot alongside broader shell status information.

### Method
GET

### Endpoint
/api/status

### Response
#### Success Response (200)
- **scan** (object) - A snapshot of the current scan status.
- **shell_status** (object) - Broader status information for the Foldergram shell.

#### Response Example
```json
{
  "scan": {
    "phase": "discovery",
    "progress": {
      "folders_discovered": 1500,
      "folders_processed": 1200
    }
  },
  "shell_status": {
    "uptime_seconds": 3600
  }
}
```

## GET /api/scan-progress

### Description
Returns the same viewer-safe scan payload as `/api/status` but specifically for lighter polling of scan progress.

### Method
GET

### Endpoint
/api/scan-progress

### Response
#### Success Response (200)
- **scan** (object) - A snapshot of the current scan status.

#### Response Example
```json
{
  "scan": {
    "phase": "derivatives",
    "progress": {
      "jobs_queued": 50,
      "jobs_completed": 30,
      "thumbnails_generated": 100
    }
  }
}
```

## GET /api/admin/scan-progress

### Description
Returns the admin-detailed scan payload, including current file and folder detail when available. This endpoint provides more granular information than `/api/scan-progress`.

### Method
GET

### Endpoint
/api/admin/scan-progress

### Response
#### Success Response (200)
- **scan** (object) - Detailed scan status including file and folder information.

#### Response Example
```json
{
  "scan": {
    "phase": "migration",
    "progress": {
      "rows_checked": 10000,
      "files_moved": 500,
      "files_repaired": 10,
      "missing_files": 2,
      "asset_key_backfills": 25
    },
    "current_file": "/path/to/current/file.jpg",
    "current_folder": "/path/to/current/folder"
  }
}
```
```

--------------------------------

### Set Reels Feed Default via PUT /api/admin/settings/reels-feed-default

Source: https://foldergram.github.io/api

Configures the default mode for the Reels feed.

```json
{
  "defaultMode": "recommended"
}
```

```json
{
  "defaultMode": "recommended"
}
```

--------------------------------

### Required Mutation Header

Source: https://foldergram.github.io/api

The x-foldergram-intent header is required for all mutating API requests.

```http
x-foldergram-intent: 1
```

--------------------------------

### PUT /api/auth/password

Source: https://foldergram.github.io/api

Sets or changes the admin password.

```APIDOC
## PUT /api/auth/password

### Description
Sets or changes the admin password. Minimum length is 8 characters.

### Method
PUT

### Endpoint
/api/auth/password

### Request Body
- **currentPassword** (string) - Optional - Required if protection is already enabled.
- **password** (string) - Required - The new password.
```

--------------------------------

### Rebuild Index

Source: https://foldergram.github.io/api

Stops the watcher, clears all indexed data (images, folders, likes, scan history), rescans the gallery root, and restarts the watcher. This is a comprehensive reset.

```http
POST /api/admin/rebuild-index
```

--------------------------------

### Foldergram API Base Paths

Source: https://foldergram.github.io/api

The Foldergram API is organized into several base paths, each serving a distinct purpose.

```APIDOC
## Foldergram API Base Paths

| Base path      | Purpose                                                                                                |
|----------------|--------------------------------------------------------------------------------------------------------|
| `/api`         | JSON API                                                                                               |
| `/thumbnails`| Protected thumbnail derivatives, served from cache or generated on demand in lazy mode                 |
| `/previews`    | Protected preview derivatives, served from cache or generated on demand in lazy mode                   |
```

--------------------------------

### POST /api/auth/logout

Source: https://foldergram.github.io/api

Clears the current browser session.

```APIDOC
## POST /api/auth/logout

### Description
Clears the current browser session cookie.

### Method
POST

### Endpoint
/api/auth/logout
```