# OPDS Acquisition

Download books and list available formats.

## Download Book with Format Conversion

**Endpoint**: `GET /opds/devices/{deviceId}/download/{bookId}`
**Auth**: Device token required

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| format | string | No | Book format: `epub` (default), `kepub` |

### Example Request

```http
GET /opds/devices/kobo-id/download/uuid-123?format=kepub
```

### Response (200 OK)

**Headers:**
- `Content-Type`: `application/epub+zip` or `application/vnd.kobo+xml+zip`
- `Content-Disposition`: attachment; filename="The Hobbit.epub"
- `X-Bookhoard-UUID`: uuid-123
- `X-Bookhoard-SHA256`: abc123... (original hash)
- `X-Bookhoard-KEPUB-SHA256`: xyz789... (KEPUB hash if format=kepub)

**Body:** Book file binary data

## List Available Formats

**Endpoint**: `GET /opds/devices/{deviceId}/formats/{bookId}`
**Auth**: Device token required

### Example Request

```http
GET /opds/devices/kobo-id/formats/uuid-123
```

### Response (200 OK)

```json
{
  "media_item_id": "uuid-123",
  "formats": [
    {
      "format_type": "epub",
      "file_path": "/path/to/book.epub",
      "file_sha256": "abc123...",
      "file_size_bytes": 2456789,
      "mime_type": "application/epub+zip",
      "available": true
    },
    {
      "format_type": "kepub",
      "file_path": "/cache/book.kepub.epub",
      "file_sha256": "xyz789...",
      "file_size_bytes": 2478932,
      "mime_type": "application/vnd.kobo+xml+zip",
      "available": true
    }
  ]
}
```

## Try It Out

<!-- API Explorer will be inserted here in Phase 3 -->