---
method: POST
path: /api/devices/:deviceId/sync/link-book
auth: jwt
area: devices
---
<!-- source: internal/handlers/matching.go:57 MatchingHandler.LinkBook -->

# Link Book

Links a device file (by path + SHA256) to a media item, optionally with a
confidence score. Used by the book-matching flow.

## Example request

```json example-request
{
  "device_file": {
    "file_path": "/books/1984.epub",
    "sha256": "abc123...",
    "title": "1984"
  },
  "media_item_id": "550e8400-e29b-41d4-a716-446655440000",
  "confidence_score": 0.95
}
```

## Example response

```json example-response
{
  "status": "linked",
  "device_file_alias": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "media_item_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_id": "770e8400-e29b-41d4-a716-446655440000",
    "file_path": "/books/1984.epub",
    "file_sha256": "abc123...",
    "confidence_score": 0.95
  }
}
```

## Request fields

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| device_file.file_path | string | no | path on the device |
| device_file.sha256 | string | no | file content hash |
| device_file.title | string | no | device-side title |
| media_item_id | string (uuid) | yes | `services.LinkBookRequest` declares it as uuid; the gate only checks the Bind struct — UNVERIFIED: confirm required tag on LinkBookRequest fields |
| confidence_score | number | no | match confidence (0-1) |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "Invalid device ID"}` / `{"error": "Invalid request body"}` | malformed id or body |
| 500 | `{"error": "Failed to link book: ..."}` | service failure |