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

​Books API

​Base URL

​List Books

​Query Parameters

​Example Request

​Response

​Get Book by ID

​Parameters

​Response

​Get Book Content

​Parameters

​Response

​Add to Reading List

​Request Body

​Response

​Update Reading Progress

​Request Body

​Response

​Get Recommendations

​Query Parameters

​Response

​Rate Limiting

Books API

Base URL

List Books

Query Parameters

Example Request

Response

Get Book by ID

Parameters

Response

Get Book Content

Parameters

Response

Add to Reading List

Request Body

Response

Update Reading Progress

Request Body

Response

Get Recommendations

Query Parameters

Response

Rate Limiting