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.88",
  "apiVersion": "v1",
  "supportedFormats": ["cbz", "zip", "epub", "pdf", "mp4", "m4v", "mov", "mkv", "avi", "webm", "..."],
  "capabilities": {
    "pdfStreaming": true,
    "pdfPageLayout": true,
    "scanSettings": true,
    "videoCatalog": true,
    "videoHls": 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. 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/:id/manifest
GET  /api/client/games/:id/file

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

PDF streaming

Release 0.88 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.88 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.