Library API

Browse library roots, inspect files, and read storage summaries.

Try it with a token

Create a bearer token with the Authentication flow before running these examples.

Library roots

List library roots

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

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/library/roots

Response:

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

Library-root management exists in the server admin surface, but the public API docs focus on read operations.

Library files

List files

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

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  "http://your-server:4000/api/library/files?mediaType=movie&search=inception&limit=10"

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.

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/library/files/1

Response:

{
  "id": 1,
  "path": "/data/movies/Inception (2010)/Inception (2010).mkv",
  "title": "Inception",
  "year": 2010,
  "mediaType": "movie",
  "overview": "A thief who steals corporate secrets through dream-sharing technology is given the inverse task of planting an idea.",
  "runtimeSeconds": 8880,
  "artwork": {
    "posterUrl": "/artwork/movies/27205/poster.jpg",
    "backdropUrl": "/artwork/movies/27205/backdrop.jpg"
  },
  "tracks": [
    { "index": 0, "type": "video", "codec": "hevc", "resolution": "2160p", "hdr": true },
    { "index": 1, "type": "audio", "codec": "eac3", "language": "en", "channels": "5.1" },
    { "index": 2, "type": "subtitle", "codec": "subrip", "language": "en", "forced": false }
  ],
  "subtitles": [
    { "path": "/data/movies/Inception (2010)/Inception (2010).en.srt", "language": "en" }
  ]
}

Metadata editing and scan orchestration are admin workflows and are intentionally not covered in detail here.

Storage analytics

Get stats

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

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/library/stats

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
  }
}