---
method: POST
path: /api/media-items/:id/rescan
auth: jwt+admin
area: media-items
---
<!-- source: internal/handlers/media.go:1765 MediaHandler.RescanMediaItem -->

# Rescan Media Item

Re-extracts metadata for one media item from its file and returns the updated
row (200, full `media_items` record — 70+ columns; the most relevant are shown
below).

Write-after-success guarantee: a failed/empty extraction never clears
scan-derived columns.

## Example response (abridged)

```json example-response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "library_id": "990e8400-e29b-41d4-a716-446655440000",
  "title": "1984",
  "author": "George Orwell",
  "file_path": "/books/1984.epub",
  "mime_type": "application/epub+zip",
  "scan_status": "completed",
  "updated_at": "2026-10-24T14:57:01Z"
}
```

The example is abridged for readability — the response carries the full
`media_items` row.

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid media item id"}` | malformed id |
| 403 | `{"error": "admin access required"}` | not an admin |
| 404 | `{"error": "media item not found"}` | no such item |
| 500 | `{"error": "..."}` | extraction/DB failure |