Skip to content

API Overview

Media Viewer exposes a RESTful API for programmatic access to all features. The API is used internally by the web frontend and can also be used for custom integrations.

Base URL

All API endpoints are prefixed with /api/ (except authentication, health, and version endpoints).

Authentication

Most endpoints require authentication via session cookie. Obtain a session by logging in through the /api/auth/login endpoint.

After successful login, a session cookie is set automatically. Include this cookie in subsequent requests.

Unauthenticated Requests

Unauthenticated requests to protected endpoints return:

HTTP/1.1 401 Unauthorized

Response Format

All responses are JSON unless otherwise noted.

Success Response

{
    "success": true,
    "data": {}
}

Error Response

{
    "success": false,
    "error": "Error message"
}

Endpoints Summary

Authentication

Method Endpoint Description
POST /api/auth/login Log in
POST /api/auth/logout Log out
GET /api/auth/check Check session status
PUT /api/auth/password Change password

Files

Method Endpoint Description
GET /api/files List directory contents
GET /api/media List media files for lightbox
GET /api/thumbnail/{path} Get thumbnail
GET /api/file/{path} Get original file

Tags

Method Endpoint Description
GET /api/tags List all tags
GET /api/tags/file Get tags for a file
POST /api/tags/file Add tag to file
DELETE /api/tags/file Remove tag from file
POST /api/tags/bulk Add tag to multiple files
DELETE /api/tags/bulk Remove tag from multiple files

Favorites

Method Endpoint Description
GET /api/favorites List favorites
POST /api/favorites Add favorite
DELETE /api/favorites Remove favorite
POST /api/favorites/bulk Add multiple favorites
Method Endpoint Description
GET /api/search Search media

System

Method Endpoint Description
GET /api/stats Get library statistics
GET /health Health check
GET /version Version information
POST /api/thumbnails/rebuild Clear and rebuild thumbnails