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
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.
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
GET /books?genre=science-fiction&reading_level=intermediate&page=1&limit=10
Response
{
"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.
GET /books/{book_id}
Authorization: Bearer YOUR_ACCESS_TOKEN
Parameters
| Parameter | Type | Required | Description |
|---|
| book_id | string | Yes | The book’s unique identifier |
Response
{
"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).
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
{
"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.
POST /books/{book_id}/reading-list
Authorization: Bearer YOUR_ACCESS_TOKEN
Request Body
{
"status": "want_to_read",
"priority": "high"
}
Response
{
"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.
PATCH /books/{book_id}/progress
Authorization: Bearer YOUR_ACCESS_TOKEN
Request Body
{
"page_number": 150,
"percentage": 39,
"time_spent": 3600
}
Response
{
"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.
GET /books/recommendations
Authorization: Bearer YOUR_ACCESS_TOKEN
Query Parameters
| Parameter | Type | Required | Description |
|---|
| limit | integer | No | Number of recommendations (default: 10) |
Response
{
"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
