---
method: POST
path: /api/libraries/:id/scan
auth: jwt+admin
area: libraries
---
<!-- source: internal/router/library.go:43 (wraps handlers/scanner.go:34 Handler.ScanLibrary) -->

# Scan Library

Enqueues a scan of one library's configured folders. The library id comes
from the path — no request body is needed (the generic `POST /api/scanner/scan`
variant is the one that takes `folder_paths`).

**Per-folder scope**: an optional body of `{"folder_path": "…"}` restricts the
scan to ONE of the library's registered folders (the per-folder Scan buttons
in the library panel). The path must be a registered folder — anything else is
a **400**. A scoped scan never runs archive reconciliation for the library's
other folders, so items outside the scanned folder cannot be marked missing
by it.

Scans are **coalesced**: if a scan for this library is already pending or
running you get **409** with the active job id instead of a second scan.

## Example response (202 Accepted)

```json example-response
{
  "message": "scan job enqueued",
  "job_id": "dd0e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}
```

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid library id"}` / `{"error": "library has no folders configured"}` / `{"error": "folder_path is not one of this library's registered folders"}` | malformed id / empty library / unregistered folder scope |
| 404 | `{"error": "library not found or has no folders"}` | unknown library |
| 409 | `{"error": "a scan for this library is already pending or running", "active_job_id": "..."}` | scan coalescing |
| 500 | `{"error": "failed to enqueue scan job: ..."}` | queue failure |