Libraries API — Trigger Library and Show Scans

The Libraries API provides two endpoints for triggering media scans. A full library scan walks the entire source directory and reconciles all media items with the ErsatzTV database. A per-show scan limits the scope to a single TV show by title, making it faster and less disruptive for large libraries.

POST /api/libraries//scan

Queues a full scan for the specified library. The scan runs asynchronously in the background and re-indexes all media items in the library’s source paths.

integer

required

The integer ID of the library to scan.

Responses

Status	Description
`200 OK`	The scan was successfully queued.
`404 Not Found`	No library with the given `id` was found.

curl -X POST http://localhost:8409/api/libraries/1/scan

Library scans run in the background worker. The 200 OK response confirms the scan was accepted, not that it is complete. Monitor ErsatzTV logs or the UI to track scan progress.

POST /api/libraries//scan-show

Queues a scan scoped to a single TV show within the specified library. ErsatzTV locates the show by its exact title, then re-indexes only that show’s episodes. This is significantly faster than a full library scan for large collections.

integer

required

The integer ID of the library that contains the show.

Request Body

string

required

The exact title of the TV show to scan. Leading and trailing whitespace is trimmed automatically. The show must already exist in the library; ErsatzTV will not discover new shows through this endpoint.

boolean

default:"false"

When true, performs a deep scan that re-reads file metadata even for items that have not changed on disk. When false (default), only new or modified files are processed.

Responses

Status	Description
`200 OK`	The show scan was successfully queued.
`400 Bad Request`	`showTitle` is missing, the library does not support per-show scanning, or the show could not be found by title in that library. The response body contains an `error` field with a description.
`404 Not Found`	No library with the given `id` was found (returned implicitly by a queuing failure).

curl -X POST http://localhost:8409/api/libraries/1/scan-show \
  -H "Content-Type: application/json" \
  -d '{"showTitle": "The Simpsons"}'

curl -X POST http://localhost:8409/api/libraries/1/scan-show \
  -H "Content-Type: application/json" \
  -d '{"showTitle": "The Simpsons", "deepScan": true}'

{
  "error": "Unable to locate show with title The Simpsons in library 1"
}

{
  "error": "ShowTitle is required"
}

The showTitle field must match exactly — including capitalization and punctuation — the title as stored in ErsatzTV’s database. If the show was imported with a specific title format, use that exact string. Fuzzy matching is not performed.

Overview

Endpoints

Libraries API — Trigger Library and Show Scans

POST /api/libraries//scan

Responses

POST /api/libraries//scan-show

Request Body

Responses

​POST /api/libraries//scan

​Responses

​POST /api/libraries//scan-show

​Request Body

​Responses

POST /api/libraries//scan

Responses

POST /api/libraries//scan-show

Request Body

Responses