Library API

Browse Local Media Store catalogs, inspect media items, view dashboard statistics, and run scan-related operations.

Try it with a token

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

Browse a catalog

GET /api/library/catalog?section=movies
Authorization: Bearer <token>

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  "http://your-server:4000/api/library/catalog?section=movies&page=1&pageSize=24&search=inception"

Query parameters:

Parameter	Type	Description
section	string	Required section key, such as movies, tv, music, books, audiobooks, comics, or games
page	number	Optional page number, starting at 1
pageSize	number	Optional page size, max 200
search	string	Full-text search against catalog titles and metadata
sort	string	Sort field supported by the selected section
sortDir	string	asc or desc
quality	string	Optional quality/resolution filter
genre	string	Optional genre filter
yearMin	number	Minimum release year
yearMax	number	Maximum release year

Paginated response:

{
  "items": [
    {
      "id": 1,
      "title": "Inception",
      "name": "Inception",
      "year": 2010,
      "mediaType": "movie",
      "kind": "file",
      "path": "/data/movies/Inception (2010)/Inception.mkv",
      "posterUrl": "/artwork/movies/27205/poster.jpg",
      "quality": "4K",
      "resolution": "2160p",
      "sizeBytes": 4294967296,
      "genres": ["Action", "Science Fiction"]
    }
  ],
  "totalCount": 342,
  "page": 1,
  "pageSize": 24,
  "totalPages": 15
}

When page and pageSize are omitted, the server can return the full section-catalog shape:

{
  "section": "movies",
  "sectionType": "video",
  "label": "Movies",
  "items": [],
  "totalCount": 342,
  "status": "ready",
  "counts": {
    "itemCount": 342,
    "rootCount": 1,
    "fallbackCount": 0
  },
  "roots": [
    {
      "path": "/data/movies",
      "directoryName": "movies"
    }
  ],
  "fallbackDirectories": []
}

Get item detail

GET /api/library/item?section=movies&path=/data/movies/Inception%20(2010)/Inception.mkv
Authorization: Bearer <token>

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  --get \
  --data-urlencode "section=movies" \
  --data-urlencode "path=/data/movies/Inception (2010)/Inception.mkv" \
  "http://your-server:4000/api/library/item"

The detail response is section-specific and can include metadata, local file information, tracks, artwork, and progress data used by the bundled player.

Dashboard statistics

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

{
  "totalFiles": 1250,
  "totalSizeBytes": 10995116277760,
  "byMediaType": {
    "movie": { "count": 342, "sizeBytes": 4398046511104 },
    "tv": { "count": 580, "sizeBytes": 5497558138880 }
  },
  "byRoot": [
    { "rootFolder": "/data/movies", "fileCount": 342, "sizeBytes": 4398046511104 }
  ],
  "byQuality": {
    "2160p": 120,
    "1080p": 680
  },
  "byCodec": {
    "h265": 420,
    "h264": 502
  },
  "recentAdditions": 12,
  "missingProbe": 3,
  "missingMetadata": 8
}

Metadata repair queue

GET /api/library/metadata/repair?state=unmatched&limit=25
Authorization: Bearer <token>

{
  "summary": {
    "total": 8,
    "unmatched": 5,
    "partial": 2,
    "locked": 1
  },
  "items": [
    {
      "id": 42,
      "title": "Unknown Movie",
      "fileName": "Unknown.Movie.mkv",
      "path": "/data/movies/Unknown.Movie.mkv",
      "section": "movies",
      "mediaType": "movie",
      "metadataMatchState": "unmatched",
      "scannedAt": "2026-06-01T12:00:00Z"
    }
  ]
}

Admins can apply manual overrides:

PATCH /api/library/file/:id/metadata
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Inception",
  "year": 2010,
  "genres": ["Action", "Science Fiction"],
  "posterUrl": "https://image.tmdb.org/t/p/w500/example.jpg"
}

Scan status and scan trigger

GET /api/library/scan/status
Authorization: Bearer <token>

{
  "scanning": true,
  "status": {
    "scanning": true,
    "rootsTotal": 3,
    "rootsCompleted": 1,
    "totals": {
      "found": 1000,
      "processed": 850,
      "new": 12,
      "updated": 4,
      "removed": 0
    }
  },
  "discoveredRoots": [
    {
      "path": "/data/movies",
      "mediaType": "movie",
      "rootType": "filesystem",
      "section": "movies"
    }
  ]
}

Start a scan as an admin:

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

{
  "rootPath": "/data/movies",
  "force": false
}

POST /api/library/scan/trigger remains available as a legacy alias.

Collections and missing media

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

Returns movie collections represented in the Local Library.

GET /api/library/missing?section=movies
Authorization: Bearer <token>

Returns missing collection parts for movies or missing episode information for TV.

Original file download

GET /api/library/file/:id/download
Authorization: Bearer <token>
Range: bytes=0-

This endpoint downloads the original library file by Local Media Store file ID. For playback by path, use Streaming API instead.