Skip to main content

Library Management API

Endpoints for creating media libraries, browsing filesystem directories, initiating background folder scans, and managing items.

List Libraries​

Returns all libraries accessible to the authenticated profile:

GET /api/libraries
Authorization: Bearer <token>

Response (200 OK)​

[
  {
    "id": 1,
    "name": "Movies",
    "kind": "movie",
    "item_count": 482,
    "roots": ["/media/movies"]
  },
  {
    "id": 2,
    "name": "TV Shows",
    "kind": "show",
    "item_count": 34,
    "roots": ["/media/tv"]
  }
]

Create Library (Admin)​

Creates a new library associated with one or more host filesystem roots:

POST /api/libraries
Authorization: Bearer <ADMIN_TOKEN>
Content-Type: application/json

{
  "name": "Anime",
  "kind": "show",
  "roots": ["/media/anime"],
  "language": "ja"
}

Response (200 OK)​

{
  "id": 3,
  "name": "Anime",
  "kind": "show"
}

Trigger Library Rescan (Admin)​

Dispatches an asynchronous background scan job to index new or modified files:

POST /api/libraries/:id/scan
Authorization: Bearer <ADMIN_TOKEN>

Response (200 OK)​

{
  "status": "scan_queued"
}

Interactive Server Directory Browser (Admin)​

Enables administrative users to navigate the host filesystem to select media folders:

GET /api/fs?path=/media
Authorization: Bearer <ADMIN_TOKEN>

Response (200 OK)​

{
  "current": "/media",
  "parent": "/",
  "directories": ["movies", "tv", "music", "photos"]
}

Update Playback Progress​

Updates the current user's watch progress for an item:

PUT /api/items/:id/progress
Authorization: Bearer <token>
Content-Type: application/json

{
  "position_s": 842.5,
  "watched": false
}

Response (200 OK)​

{
  "ok": true
}