API Reference

The BookWish API is a RESTful API that provides access to all platform features including books, wishlists, stores, inventory, social features, and more.

Base URL

All API requests should be made to:

https://api.bookwish.app

For local development:

http://localhost:3000

Authentication

Most endpoints require authentication using JWT (JSON Web Tokens). Include your access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for detailed information about obtaining and using tokens.

Request Format

• Content-Type: application/json
• Method: Standard HTTP methods (GET, POST, PUT, DELETE)
• Body: JSON payload for POST/PUT requests

Example Request

curl -X POST https://api.bookwish.app/wishlists \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bookId": "123", "condition": "new"}'

Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

Success Response

{
  "user": {
    "id": "123",
    "displayName": "John Doe",
    "email": "john@example.com"
  }
}

Error Response

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    {
      "path": "email",
      "message": "Invalid email format"
    }
  ]
}

See Errors for detailed error handling information.

Pagination

List endpoints support pagination using query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	20	Items per page (max 100)

Example Paginated Request

GET /wishlists?page=2&limit=50

Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 250,
    "totalPages": 5
  }
}

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint and user tier.

• Rate limit information is returned in response headers
• Exceeded limits return 429 Too Many Requests
• Free tier users have monthly content creation limits

See Rate Limiting for specific limits and best practices.

Endpoint Categories

Category	Base Path	Description
Authentication	/auth	User signup, login, token refresh
Users	/users	User profiles, preferences, followers
Books	/books	Book search and information
Wishlists	/wishlists	User wishlists and book wants
Stores	/stores	Bookstore profiles and inventory
Orders	/orders	Order management and fulfillment
Cart	/cart	Shopping cart operations
Checkout	/checkout	Checkout and payment processing
Inventory	/stores/:id/inventory	Store inventory management
POS	/pos	Point-of-sale operations
Lines	/lines	Social feed posts (scribbles)
Reviews	/reviews	Book reviews
Notes	/notes	Private book notes
Feed	/feed	Social content feed
Search	/search	Global search across content
Follows	/follows	Follow relationships
Clubs	/clubs	Book clubs
Challenges	/challenges	Reading challenges
Notifications	/notifications	User notifications
Billing	/billing	Subscription management
Moderation	/reports, /admin	Content moderation

Health Check

The API provides a health check endpoint for monitoring:

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-12-08T10:30:00.000Z"
}

Versioning

The API is currently in version 1. Future versions will be indicated in the base path (e.g., /v2/).

Support

For API support and questions:

• GitHub Issues: bookwish/api
• Email: api@bookwish.app
• Documentation: docs.bookwish.app