> ## Documentation Index
> Fetch the complete documentation index at: https://docs.readingsteps.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Books API

> API endpoints for managing books and reading content.

# Books API

The Books API provides access to the ReadingSteps book library and reading content.

## Base URL

```
https://api.readingsteps.uk/v1/books
```

## List Books

Retrieve a list of books with optional filtering and pagination.

```bash theme={null}
GET /books
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Query Parameters

| Parameter      | Type    | Required | Description                                                |
| -------------- | ------- | -------- | ---------------------------------------------------------- |
| page           | integer | No       | Page number (default: 1)                                   |
| limit          | integer | No       | Items per page (default: 20, max: 100)                     |
| genre          | string  | No       | Filter by genre                                            |
| reading\_level | string  | No       | Filter by reading level (beginner, intermediate, advanced) |
| search         | string  | No       | Search query for title or author                           |

### Example Request

```bash theme={null}
GET /books?genre=science-fiction&reading_level=intermediate&page=1&limit=10
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "bk_abc123",
      "title": "The Martian",
      "author": "Andy Weir",
      "cover": "https://cdn.readingsteps.uk/covers/bk_abc123.jpg",
      "genre": "science-fiction",
      "reading_level": "intermediate",
      "pages": 384,
      "description": "An astronaut becomes stranded on Mars...",
      "rating": 4.5,
      "published_date": "2014-02-11"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "total_pages": 16
  }
}
```

## Get Book by ID

Retrieve detailed information about a specific book.

```bash theme={null}
GET /books/{book_id}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Parameters

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| book\_id  | string | Yes      | The book's unique identifier |

### Response

```json theme={null}
{
  "id": "bk_abc123",
  "title": "The Martian",
  "author": "Andy Weir",
  "cover": "https://cdn.readingsteps.uk/covers/bk_abc123.jpg",
  "genre": "science-fiction",
  "reading_level": "intermediate",
  "pages": 384,
  "description": "An astronaut becomes stranded on Mars...",
  "rating": 4.5,
  "published_date": "2014-02-11",
  "isbn": "9780804139021",
  "language": "en",
  "chapters": [
    {
      "id": "ch_001",
      "title": "Chapter 1",
      "page_start": 1,
      "page_end": 25
    }
  ]
}
```

## Get Book Content

Retrieve the actual content of a book (requires read permission).

```bash theme={null}
GET /books/{book_id}/content
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Parameters

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| book\_id  | string | Yes      | The book's unique identifier |
| chapter   | string | No       | Specific chapter to retrieve |

### Response

```json theme={null}
{
  "book_id": "bk_abc123",
  "chapter_id": "ch_001",
  "title": "Chapter 1",
  "content": "I'm pretty much screwed...",
  "page_number": 1,
  "word_count": 1250
}
```

## Add to Reading List

Add a book to the authenticated user's reading list.

```bash theme={null}
POST /books/{book_id}/reading-list
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Request Body

```json theme={null}
{
  "status": "want_to_read",
  "priority": "high"
}
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Book added to reading list",
  "reading_list_item": {
    "id": "rl_xyz789",
    "book_id": "bk_abc123",
    "status": "want_to_read",
    "added_at": "2024-01-15T10:30:00Z"
  }
}
```

## Update Reading Progress

Update the user's reading progress for a specific book.

```bash theme={null}
PATCH /books/{book_id}/progress
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Request Body

```json theme={null}
{
  "page_number": 150,
  "percentage": 39,
  "time_spent": 3600
}
```

### Response

```json theme={null}
{
  "success": true,
  "progress": {
    "book_id": "bk_abc123",
    "page_number": 150,
    "percentage": 39,
    "time_spent": 3600,
    "last_read": "2024-01-15T10:30:00Z"
  }
}
```

## Get Recommendations

Get personalized book recommendations for the authenticated user.

```bash theme={null}
GET /books/recommendations
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Query Parameters

| Parameter | Type    | Required | Description                             |
| --------- | ------- | -------- | --------------------------------------- |
| limit     | integer | No       | Number of recommendations (default: 10) |

### Response

```json theme={null}
{
  "recommendations": [
    {
      "book": {
        "id": "bk_def456",
        "title": "Project Hail Mary",
        "author": "Andy Weir"
      },
      "reason": "Based on your interest in science fiction",
      "confidence": 0.92
    }
  ]
}
```

## Rate Limiting

The Books API has the following rate limits:

* **Anonymous**: 100 requests per hour
* **Authenticated**: 1000 requests per hour
* **Premium**: 10000 requests per hour

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```