---
method: POST
path: /api/scanner/scan
auth: jwt+admin
area: scanner
---
<!-- source: internal/handlers/scanner.go:34 Handler.ScanLibrary -->

# Scan Library

Initiate a one-time scan of a library for ebooks, manga, or comics.

**Endpoint**: `POST /api/scanner/scan`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`

## Request Body

| Field      | Type          | Required | Description                                               |
| ---------- | ------------- | -------- | --------------------------------------------------------- |
| library_id | string (UUID) | Yes      | Library UUID to scan (supports ebooks, manga, and comics) |
| recursive  | boolean       | No       | Scan subdirectories recursively (default: true)           |
| force      | boolean       | No       | Force rescan of existing files (default: false)           |

## Supported Formats

The scanner automatically detects and processes files based on the library type:

**Ebooks:** .epub, .pdf, .mobi, .txt, .rtf, .docx, .fb2, .pdb

**Comics:** .cbz, .cbr, .cb7, .cbt, .pdf

**Manga:** .cbz, .cbr, .png, .jpg, .jpeg, .gif, .bmp, .webp

### Example Request

```json example-request
{
  "library_id": "550e8400-e29b-41d4-a716-446655440000",
  "force": false
}
```

## Response (202 Accepted)

```json example-response
{
  "message": "scan job enqueued",
  "job_id": "b3d3a0c2-8f4e-4c1d-9a2b-6e5f1a7c9d01",
  "status": "pending"
}
```

A scan for the same library already pending or running returns **409** with
`{"error": "a scan for this library is already pending or running", "active_job_id": "..."}`.

## Error Responses

| Code | Description                         |
| ---- | ----------------------------------- |
| 400  | Invalid request data                |
| 401  | Invalid or expired token            |
| 403  | User does not have admin privileges |
| 404  | Library not found                   |