Lines API

Endpoints for creating and managing social posts about books (called "Lines"). All endpoints require authentication.

Create Line

Create a new social post about a book.

POST /lines

Authentication

Required (Bearer token)

Rate Limits

Free tier: 50 posts per month
Premium tier: Unlimited
Bookstore tier: Unlimited

Request Body

{
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "content": "This book completely changed my perspective on teenage rebellion and identity!",
  "pageNumber": 187,
  "clubId": null,
  "challengeId": null
}

Response

{
  "id": "aa0e8400-e29b-41d4-a716-446655440005",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
    "tier": "premium"
  },
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "content": "This book completely changed my perspective on teenage rebellion and identity!",
  "pageNumber": 187,
  "likeCount": 0,
  "replyCount": 0,
  "isLiked": false,
  "clubId": null,
  "challengeId": null,
  "createdAt": "2024-03-21T14:30:00Z",
  "updatedAt": "2024-03-21T14:30:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Monthly post limit reached (free tier)
404 NotFound - Book not found
429 TooManyRequests - Rate limit exceeded
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/lines" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
    "content": "This book completely changed my perspective!",
    "pageNumber": 187
  }'

Get Line

Get a specific line by ID.

GET /lines/:id

Authentication

Required (Bearer token)

Path Parameters

id - Line ID

Response

{
  "id": "aa0e8400-e29b-41d4-a716-446655440005",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
    "tier": "premium"
  },
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "content": "This book completely changed my perspective on teenage rebellion and identity!",
  "pageNumber": 187,
  "likeCount": 42,
  "replyCount": 8,
  "isLiked": true,
  "clubId": null,
  "challengeId": null,
  "createdAt": "2024-03-20T14:30:00Z",
  "updatedAt": "2024-03-20T14:30:00Z"
}

Errors

401 Unauthorized - Not authenticated
404 NotFound - Line not found
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Line

Update a line's content.

PUT /lines/:id

Authentication

Required (Bearer token - line author only)

Path Parameters

id - Line ID

Request Body

{
  "content": "Updated: This book completely transformed my understanding of adolescent psychology!",
  "pageNumber": 187
}

Response

{
  "id": "aa0e8400-e29b-41d4-a716-446655440005",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "content": "Updated: This book completely transformed my understanding of adolescent psychology!",
  "pageNumber": 187,
  "likeCount": 42,
  "replyCount": 8,
  "createdAt": "2024-03-20T14:30:00Z",
  "updatedAt": "2024-03-21T15:00:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Not the line author
404 NotFound - Line not found
429 TooManyRequests - Rate limit exceeded
500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated: This book completely transformed my understanding!",
    "pageNumber": 187
  }'

Delete Line

Delete a line.

DELETE /lines/:id

Authentication

Required (Bearer token - line author only)

Path Parameters

id - Line ID

Response

{
  "success": true,
  "message": "Line deleted successfully"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not the line author
404 NotFound - Line not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005" \
  -H "Authorization: Bearer YOUR_TOKEN"

Like Line

Like a line.

POST /lines/:id/like

Authentication

Required (Bearer token)

Path Parameters

id - Line ID

Response

{
  "success": true,
  "likeCount": 43,
  "isLiked": true
}

Errors

400 ValidationError - Already liked
401 Unauthorized - Not authenticated
404 NotFound - Line not found
429 TooManyRequests - Rate limit exceeded
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005/like" \
  -H "Authorization: Bearer YOUR_TOKEN"

Unlike Line

Remove like from a line.

DELETE /lines/:id/like

Authentication

Required (Bearer token)

Path Parameters

id - Line ID

Response

{
  "success": true,
  "likeCount": 42,
  "isLiked": false
}

Errors

400 ValidationError - Not liked
401 Unauthorized - Not authenticated
404 NotFound - Line not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005/like" \
  -H "Authorization: Bearer YOUR_TOKEN"

Reply to Line

Create a reply to a line.

POST /lines/:id/replies

Authentication

Required (Bearer token)

Path Parameters

id - Line ID (parent line)

Rate Limits

Free tier: 50 replies per month (counted toward monthly post limit)
Premium tier: Unlimited
Bookstore tier: Unlimited

Request Body

{
  "content": "I completely agree! The character development is incredible."
}

Response

{
  "id": "reply-001",
  "lineId": "aa0e8400-e29b-41d4-a716-446655440005",
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "username": "janedoe",
    "displayName": "Jane Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/janedoe.jpg",
    "tier": "free"
  },
  "content": "I completely agree! The character development is incredible.",
  "createdAt": "2024-03-21T15:30:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Monthly post limit reached (free tier)
404 NotFound - Line not found
429 TooManyRequests - Rate limit exceeded
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005/replies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I completely agree! The character development is incredible."
  }'

Get Replies

Get all replies for a line.

GET /lines/:id/replies

Authentication

Required (Bearer token)

Path Parameters

id - Line ID

Query Parameters

cursor (optional) - Pagination cursor
limit (optional) - Number of items (1-100, default: 20)

Response

{
  "items": [
    {
      "id": "reply-001",
      "lineId": "aa0e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "username": "janedoe",
        "displayName": "Jane Doe",
        "avatarUrl": "https://cdn.bookwish.app/avatars/janedoe.jpg",
        "tier": "premium"
      },
      "content": "I completely agree! The character development is incredible.",
      "createdAt": "2024-03-21T15:30:00Z"
    }
  ],
  "nextCursor": "reply-002",
  "hasMore": false
}

Errors

401 Unauthorized - Not authenticated
404 NotFound - Line not found
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005/replies?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Reply

Delete a reply.

DELETE /lines/:lineId/replies/:replyId

Authentication

Required (Bearer token - reply author only)

Path Parameters

lineId - Line ID (parent line)
replyId - Reply ID

Response

{
  "success": true,
  "message": "Reply deleted successfully"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not the reply author
404 NotFound - Line or reply not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/lines/aa0e8400-e29b-41d4-a716-446655440005/replies/reply-001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Club Lines

Get lines posted in a specific book club.

GET /lines/club/:clubId

Authentication

Required (Bearer token)

Path Parameters

clubId - Club ID

Query Parameters

cursor (optional) - Pagination cursor
limit (optional) - Number of items (1-100, default: 20)

Response

{
  "items": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440010",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "username": "johndoe",
        "displayName": "John Doe",
        "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg"
      },
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "book": {
        "title": "The Catcher in the Rye",
        "authors": ["J.D. Salinger"],
        "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
      },
      "content": "Great discussion today about Holden's character arc!",
      "clubId": "770e8400-e29b-41d4-a716-446655440002",
      "likeCount": 12,
      "replyCount": 5,
      "isLiked": false,
      "createdAt": "2024-03-21T18:00:00Z"
    }
  ],
  "nextCursor": "aa0e8400-e29b-41d4-a716-446655440011"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not a club member (for private clubs)
404 NotFound - Club not found
500 InternalServerError - Server error

Get Challenge Lines

Get lines posted in a specific reading challenge.

GET /lines/challenge/:challengeId

Authentication

Required (Bearer token)

Path Parameters

challengeId - Challenge ID

Query Parameters

cursor (optional) - Pagination cursor
limit (optional) - Number of items (1-100, default: 20)

Response

{
  "items": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440015",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "username": "johndoe",
        "displayName": "John Doe",
        "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg"
      },
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "book": {
        "title": "The Catcher in the Rye",
        "authors": ["J.D. Salinger"],
        "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
      },
      "content": "Book #15 of my 2024 reading challenge complete!",
      "challengeId": "880e8400-e29b-41d4-a716-446655440003",
      "likeCount": 8,
      "replyCount": 3,
      "isLiked": true,
      "createdAt": "2024-03-21T20:00:00Z"
    }
  ],
  "nextCursor": "aa0e8400-e29b-41d4-a716-446655440016"
}

Errors

401 Unauthorized - Not authenticated
404 NotFound - Challenge not found
500 InternalServerError - Server error

Line Object Fields

Field	Type	Description
`id`	string	Unique line identifier
`userId`	string	Author's user ID
`user`	object	Author's user details
`bookId`	string	Book ID
`book`	object	Book details
`content`	string	Line content text
`pageNumber`	number	Page number reference (optional)
`likeCount`	number	Number of likes
`replyCount`	number	Number of replies
`isLiked`	boolean	Whether current user liked this line
`clubId`	string	Club ID (if posted in a club)
`challengeId`	string	Challenge ID (if posted in a challenge)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Create Line​

Authentication​

Rate Limits​

Request Body​

Response​

Errors​

Example​

Get Line​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Update Line​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Delete Line​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Like Line​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Unlike Line​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Reply to Line​

Authentication​

Path Parameters​

Rate Limits​

Request Body​

Response​

Errors​

Example​

Get Replies​

Authentication​

Path Parameters​

Query Parameters​

Response​

Errors​

Example​

Delete Reply​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Get Club Lines​

Authentication​

Path Parameters​

Query Parameters​

Response​

Errors​

Get Challenge Lines​

Authentication​

Path Parameters​

Query Parameters​

Response​

Errors​

Line Object Fields​

Create Line

Authentication

Rate Limits

Request Body

Response

Errors

Example

Get Line

Authentication

Path Parameters

Response

Errors

Example

Update Line

Authentication

Path Parameters

Request Body

Response

Errors

Example

Delete Line

Authentication

Path Parameters

Response

Errors

Example

Like Line

Authentication

Path Parameters

Response

Errors

Example

Unlike Line

Authentication

Path Parameters

Response

Errors

Example

Reply to Line

Authentication

Path Parameters

Rate Limits

Request Body

Response

Errors

Example

Get Replies

Authentication

Path Parameters

Query Parameters

Response

Errors

Example

Delete Reply

Authentication

Path Parameters

Response

Errors

Example

Get Club Lines

Authentication

Path Parameters

Query Parameters

Response

Errors

Get Challenge Lines

Authentication

Path Parameters

Query Parameters

Response

Errors

Line Object Fields