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": "0.993",
  "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
  }
}

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

Release 0.993 adds an authenticated server-owned platform catalog. 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

Release 0.978 adds profile-scoped play-time synchronization. Native emulators can report accumulated seconds with stable session IDs, and FolioSpace records first played, last played, total play time, and launch count without double-counting heartbeat retries or out-of-order requests.

PDF streaming

Release 0.978 adds 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

Release 0.978 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.