Library API

Manage library roots, browse files, edit metadata, and trigger scans.

Library roots

List library roots

GET /api/library/roots
Authorization: Bearer <token>

Response:

[
  {
    "id": 1,
    "path": "/data/movies",
    "name": "Movies",
    "mediaType": "movie",
    "fileCount": 342,
    "totalSizeBytes": 2748779069440,
    "lastScanAt": "2024-01-01T12:00:00Z"
  }
]

Add library root

POST /api/library/roots
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "path": "/data/tv",
  "name": "TV Shows",
  "mediaType": "tv"
}

Response: The created library root object.

Remove library root

DELETE /api/library/roots/:id
Authorization: Bearer <admin-token>

Removes the library root and its metadata from the database. Files on disk are not deleted.

Library files

List files

GET /api/library/files
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Description
mediaType	string	Filter by media type: movie, tv, music, book, audiobook, comic, game
rootId	number	Filter by library root ID
search	string	Full-text search on title and metadata
sort	string	Sort field: title, addedAt, year, size
order	string	asc or desc
limit	number	Max results (default: 50)
offset	number	Pagination offset

Response:

{
  "items": [
    {
      "id": 1,
      "path": "/data/movies/Inception (2010)/Inception (2010).mkv",
      "title": "Inception",
      "year": 2010,
      "mediaType": "movie",
      "sizeBytes": 4294967296,
      "duration": 8880,
      "codec": "h265",
      "resolution": "2160p",
      "hdr": true,
      "container": "mkv",
      "addedAt": "2024-01-01T12:00:00Z",
      "metadata": {
        "tmdbId": 27205,
        "overview": "A thief who steals corporate secrets...",
        "genres": ["Action", "Science Fiction"],
        "posterUrl": "/artwork/movies/27205/poster.jpg",
        "rating": 8.4
      }
    }
  ],
  "total": 342,
  "limit": 50,
  "offset": 0
}

Get file detail

GET /api/library/files/:id
Authorization: Bearer <token>

Returns full file detail including all metadata, embedded tracks (audio, subtitle, video), and external subtitle files.

Edit metadata

PUT /api/library/files/:id/metadata
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "title": "Corrected Title",
  "year": 2010,
  "tmdbId": 27205,
  "overview": "Custom overview text"
}

Scanning

Trigger scan

POST /api/library/scan
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "rootId": 1
}

Omit rootId to scan all library roots. The scan runs asynchronously in the background.

Response:

{
  "jobId": "scan-1704067200",
  "status": "started"
}

Storage analytics

Get stats

GET /api/library/stats
Authorization: Bearer <token>

Response:

{
  "totalFiles": 1250,
  "totalSizeBytes": 10995116277760,
  "byMediaType": {
    "movie": { "count": 342, "sizeBytes": 4398046511104 },
    "tv": { "count": 580, "sizeBytes": 5497558138880 },
    "music": { "count": 328, "sizeBytes": 1099511627776 }
  },
  "byCodec": {
    "h265": 420,
    "h264": 502
  },
  "byResolution": {
    "2160p": 120,
    "1080p": 680,
    "720p": 122
  }
}