Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShaneIsrael/fireshare/llms.txt

Use this file to discover all available pages before exploring further.

Fireshare includes a full image library that runs alongside the video library. Mount a directory at /images, and Fireshare will scan it, generate thumbnails, produce WebP-optimized versions for fast delivery, and assign every image a permanent shareable URL. The same game and tag organization system used for videos applies to images, making it straightforward to keep your screenshots and clips filed together.

​
Volume Mount Requirement

The image library requires a /images volume mount in your Docker configuration. Without it the image scanner will not run and the image API endpoints will return 503. 
volumes:
  - /path/to/your/images:/images
If you add the /images mount to an existing Fireshare instance that did not previously have one, restart the container to pick up the new mount. The image scanner starts automatically on the next scan cycle.

​
Supported Formats

ExtensionMIME type
.jpg / .jpegimage/jpeg
.pngimage/png
.webpimage/webp
.gifimage/gif
Files with other extensions are ignored by the scanner and rejected at upload endpoints.

​
Auto-Scan and Directory Structure

The image scanner mirrors the video scanner: it runs on the same MINUTES_BETWEEN_VIDEO_SCANS interval and walks the entire /images directory tree. Each immediate subdirectory becomes a named folder in the UI under the Images section. 
/images
├── Apex Legends/          ← "Apex Legends" image folder
│   ├── screenshot1.png
│   └── screenshot2.jpg
├── Warzone/               ← "Warzone" image folder
│   └── win.webp
└── wallpaper.jpg          ← scanned, no folder
Each folder is represented in the MediaFolder table with media_type = "image". Folders can be shared via a unique URL and their privacy can be toggled independently of the images they contain.

​
Unique Share URLs

Every scanned image receives a 32-character hex image_id and is accessible at: 
https://<your-domain>/i/<image_id>
Visiting this URL serves an Open Graph metadata page that renders a rich preview card in Discord, Slack, and other platforms — including the image itself, title, and linked game name (when set). A direct link to the image file is also available via the API. No viewer account is required to access a public image URL. Private images return 401 to unauthenticated requests.

​
Image Metadata

Each image’s metadata is stored in the ImageInfo model:
FieldDescription
titleDisplay name (defaults to the filename without extension)
descriptionOptional freeform caption shown on the image detail page
privateWhether the image is hidden from public listings (default: true)
widthNative width in pixels, extracted at scan time
heightNative height in pixels, extracted at scan time
file_sizeSize of the source file in bytes
has_webptrue when a full-quality WebP conversion exists
has_thumbnailtrue when a thumbnail WebP has been generated
Metadata can be updated by an authenticated admin via: 
PUT /api/image/details/<image_id>
Content-Type: application/json

{
  "title": "My Best Clutch",
  "description": "1v5 last circle",
  "private": false
}

​
Privacy Default

Like videos, all newly scanned images default to private: true. The global default is controlled by the image_defaults.private key in config.json. A private image is still reachable via its direct /i/<image_id> URL but will not appear in any public listing.

​
Thumbnails and WebP Delivery

When an image is scanned for the first time, Fireshare generates two derived files stored in /processed/derived/<image_id>/:
FilePurpose
image.webpFull-quality WebP conversion for fast delivery
thumbnail.webpResized WebP used for grid/card previews
When a client requests an image, Fireshare prefers the WebP version over the original symlink:
  1. If image.webp exists → serve it with image/webp.
  2. Otherwise → serve the original file via the symlink at /processed/image_links/<image_id><ext>.
Thumbnail requests follow the same priority order: thumbnail.webp → image.webp → original file.

​
Serving Image Files

EndpointDescription
GET /api/image?id=<image_id>Serve the image (WebP if available, else original)
GET /api/image/original?id=<image_id>Download the unmodified original file
GET /api/image/thumbnail?id=<image_id>Serve the thumbnail WebP

​
Game and Tag Linking

Images participate in the same game and tag system as videos.

​
Linking an Image to a Game

POST /api/images/<image_id>/game
Content-Type: application/json

{"game_id": 42}

DELETE /api/images/<image_id>/game
Image folder rules (ImageFolderRule model) work identically to video folder rules: mapping a subfolder of /images to a game automatically links every image in that folder to the game. 
POST /api/image-folder-rules
Content-Type: application/json

{"folder_path": "Apex Legends", "game_id": 42}

​
Applying Tags to Images

POST /api/images/<image_id>/tags
Content-Type: application/json

{"tag_id": 7}

DELETE /api/images/<image_id>/tags/<tag_id>
Tags applied to images appear in the same tag listing at /tags alongside video counts, and the tag search syntax (#tagname) works identically in the image library.

​
View Count Tracking

The image library tracks unique views per IP address, mirroring the video view system. Views are recorded by posting to: 
POST /api/image/view
Content-Type: application/json

{"image_id": "<image_id>"}
The count is returned as part of every image listing response and is visible on the image detail page.

​
File Manager

The admin file manager at /files covers images in addition to videos. From there you can rename files, move them between folders, toggle privacy in bulk, and delete images. Deleting an image through the file manager removes the source file, the symlink in /processed/image_links/, the derived directory in /processed/derived/, and all associated database records (ImageInfo, ImageGameLink, ImageTagLink, ImageView).

Video Library

See how the video library scan and metadata extraction work — the image library follows the same patterns.

Games & Tags

Organize images by game with SteamGridDB cover art and apply cross-category tags.

Uploads

Upload screenshots directly through the browser alongside video uploads.

File Manager

Rename, move, and bulk-manage images and videos from the admin file manager.

Build docs developers (and LLMs) love

Get started for freeTalk to us