A stable HTTP surface for native clients.

Base and auth

Base URL: http://your-nas-ip:8080
Stable prefix: /api/client
Authorization: Bearer <token>

Authentication is optional. When enabled, native clients should send the bearer token on every /api/* request.

Service info example

{
  "serviceName": "FolioSpace Library",
  "serviceVersion": "1.01",
  "apiVersion": "v1",
  "supportedFormats": ["cbz", "zip", "epub", "pdf", "mp4", "m4v", "mov", "mkv", "avi", "webm", "..."],
  "capabilities": {
    "pdfStreaming": true,
    "pdfPageLayout": true,
    "scanSettings": true,
    "videoCatalog": true,
    "videoHls": true,
    "gamePlayStats": true,
    "gamePlatformCatalog": true
  }
}

Current service release

FolioSpace Library 1.01 reports serviceVersion: "1.01" and keeps the v1 client contract stable. The release adds audited MAME content-equivalence support for compatible runtime updates; clients should still rely on manifests and Resolver results for launch readiness instead of assuming platform compatibility.

Recommended client flow

1. Call GET /api/auth/status.
2. Store the access key in the native keychain if auth is enabled.
3. Call GET /api/client/info.
4. Call GET /api/client/home for the first screen.
5. Open books with GET /api/client/books/{bookId}/manifest.
6. Sync private state and progress through the API.
7. Open games with GET /api/client/games/{gameId}/manifest.
8. Sync game play time with GET and PUT /api/client/games/{gameId}/play-stats.
9. Open videos with GET /api/client/videos/{videoId}/manifest.

Important endpoints

GET  /api/auth/status
POST /api/auth/check
POST /api/auth/logout

GET  /api/setup/status
POST /api/setup/initialize
GET  /api/config/directory-roots

GET  /api/client/info
GET  /api/client/home
GET  /api/client/search?q=...
GET  /api/client/preferences
PUT  /api/client/preferences

GET  /api/settings/scan
PUT  /api/settings/scan

GET  /api/client/books/:id/manifest
GET  /api/client/books/:id/private-state
PUT  /api/client/books/:id/private-state

	GET  /api/client/games
	GET  /api/client/games/facets
	GET  /api/client/games/platforms
	GET  /api/client/games/:id/manifest
GET  /api/client/games/:id/file
GET  /api/client/games/:id/play-stats
PUT  /api/client/games/:id/play-stats

GET  /api/client/videos
GET  /api/client/videos/:id/manifest
GET  /api/client/videos/:id/file
GET  /api/client/videos/:id/hls/index.m3u8
GET  /api/client/videos/:id/transcode/status
GET  /api/client/videos/transcode/status
GET  /api/videos/:id/thumbnail

Dynamic game-platform catalog

The authenticated server-owned platform catalog introduced in 0.993 remains available in 1.01. Clients can build game-system filters without shipping a hard-coded platform list and automatically discover newly supported systems.

GET /api/client/games/platforms

{
  "items": [
    {
      "platform": "virtualboy",
      "title": "Virtual Boy",
      "aliases": ["virtual-boy", "virtual boy"],
      "count": 22,
      "available": true
    }
  ]
}

Use GET /api/client/games/facets as an inventory-only fallback on older servers. The catalog reports recognized platforms; launch readiness still comes from the game manifest or Resolver flow.

Game play stats

Profile-scoped play-time synchronization, introduced in 0.978, remains available in 1.01. Native emulators can report accumulated seconds with stable session IDs, and FolioSpace Library records first played, last played, total play time, and launch count without double-counting heartbeat retries or out-of-order requests.

PDF streaming

PDF indexing, first-page preview covers, and single-page or double-page web reading. PDF content is fetched through HTTP Range streaming by service URL, so clients do not need access to real NAS file paths.

Video catalog and HLS bridge

FolioSpace Library indexes local video files and exposes client-safe manifests with direct file URLs, HLS URLs, thumbnails, and transcode status URLs. Browser-compatible files stream directly through HTTP Range requests. Incompatible codecs, including many HEVC/H.265 assets, can be converted on demand to cached H.264/AAC HLS output.

HLS transcodes use a single active queue and cached output under the service config cache. Clients should poll the per-video or global transcode status endpoint instead of assuming conversion is instant.

Scan settings

Clients can read and save scan worker settings to match NAS performance. Small NAS devices can use conservative worker counts; faster local servers can increase concurrency.

GET /api/settings/scan
PUT /api/settings/scan

{
  "scanWorkers": 4
}

Path privacy rule

Client API responses should not expose real absolute NAS paths. Clients receive service URLs for covers, pages, EPUB resources, and game files, video streams, HLS playlists, and thumbnails.