Skip to main content

Users API

Endpoints for managing user profiles, preferences, and viewing public user data.

Get Current User​

Get the authenticated user's profile.

GET /users/me

Authentication​

Required (Bearer token)

Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "johndoe",
  "email": "john@example.com",
  "displayName": "John Doe",
  "bio": "Book lover and avid reader",
  "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
  "tier": "premium",
  "isGuest": false,
  "homeStoreId": "660e8400-e29b-41d4-a716-446655440001",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Errors​

  • 401 Unauthorized - Not authenticated

Update Current User​

Update the authenticated user's profile.

PUT /users/me

Authentication​

Required (Bearer token)

Request Body​

{
  "displayName": "John Doe Jr.",
  "bio": "Passionate about science fiction and fantasy novels",
  "username": "johndoe_jr"
}

Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "johndoe_jr",
  "email": "john@example.com",
  "displayName": "John Doe Jr.",
  "bio": "Passionate about science fiction and fantasy novels",
  "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
  "tier": "premium",
  "isGuest": false,
  "homeStoreId": "660e8400-e29b-41d4-a716-446655440001",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-21T09:15:00Z"
}

Errors​

  • 400 ValidationError - Invalid request body
  • 401 Unauthorized - Not authenticated
  • 409 Conflict - Username already taken

Change Password​

Change the authenticated user's password.

PUT /users/me/password

Authentication​

Required (Bearer token)

Request Body​

{
  "currentPassword": "OldP@ssw0rd",
  "newPassword": "NewSecureP@ssw0rd"
}

Response​

{
  "success": true,
  "message": "Password updated successfully"
}

Errors​

  • 400 ValidationError - Invalid request body
  • 401 Unauthorized - Not authenticated or incorrect current password
  • 500 InternalServerError - Server error

Upload Avatar​

Upload a user avatar image.

POST /users/me/avatar

Authentication​

Required (Bearer token)

Request Body​

  • Content-Type: multipart/form-data
  • Field name: avatar
  • Accepted formats: JPG, PNG, GIF
  • Max file size: 5MB

Response​

{
  "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg"
}

Errors​

  • 400 ValidationError - Invalid file format or size
  • 401 Unauthorized - Not authenticated
  • 500 InternalServerError - Server error

Get Home Store​

Get the authenticated user's home store.

GET /users/me/home-store

Authentication​

Required (Bearer token)

Response​

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Downtown Books",
  "slug": "downtown-books",
  "description": "Your neighborhood independent bookstore",
  "logoUrl": "https://cdn.bookwish.app/stores/downtown-books.jpg",
  "addressLine1": "123 Main St",
  "city": "Springfield",
  "state": "IL",
  "country": "US"
}

Errors​

  • 401 Unauthorized - Not authenticated
  • 404 NotFound - No home store set

Set Home Store​

Set the authenticated user's home store.

PUT /users/me/home-store

Authentication​

Required (Bearer token)

Request Body​

{
  "storeId": "660e8400-e29b-41d4-a716-446655440001"
}

Response​

{
  "success": true,
  "homeStoreId": "660e8400-e29b-41d4-a716-446655440001"
}

Errors​

  • 400 ValidationError - Invalid store ID
  • 401 Unauthorized - Not authenticated
  • 404 NotFound - Store not found

Clear Home Store​

Remove the authenticated user's home store.

DELETE /users/me/home-store

Authentication​

Required (Bearer token)

Response​

{
  "success": true,
  "message": "Home store cleared"
}

Errors​

  • 401 Unauthorized - Not authenticated

Get User's Clubs​

Get clubs the authenticated user has joined.

GET /users/me/clubs

Authentication​

Required (Bearer token)

Response​

{
  "clubs": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Science Fiction Book Club",
      "description": "Monthly sci-fi discussions",
      "isPublic": true,
      "memberCount": 24,
      "hostId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-10T12:00:00Z"
    }
  ]
}

Errors​

  • 401 Unauthorized - Not authenticated

Get User's Challenges​

Get challenges the authenticated user has joined.

GET /users/me/challenges

Authentication​

Required (Bearer token)

Response​

{
  "challenges": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "2024 Reading Challenge",
      "description": "Read 50 books in 2024",
      "goal": 50,
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "participantCount": 152,
      "hostId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2023-12-15T10:00:00Z"
    }
  ]
}

Errors​

  • 401 Unauthorized - Not authenticated

Get User Profile by ID​

Get a user's public profile by user ID.

GET /users/:userId

Authentication​

None required

Path Parameters​

  • userId - User ID

Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "johndoe",
  "displayName": "John Doe",
  "bio": "Book lover and avid reader",
  "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
  "tier": "premium",
  "createdAt": "2024-01-15T10:30:00Z"
}

Errors​

  • 404 NotFound - User not found

Get User Profile by Username​

Get a user's public profile by username.

GET /users/username/:username

Authentication​

None required

Path Parameters​

  • username - Username

Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "johndoe",
  "displayName": "John Doe",
  "bio": "Book lover and avid reader",
  "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
  "tier": "premium",
  "followerCount": 145,
  "followingCount": 89,
  "createdAt": "2024-01-15T10:30:00Z"
}

Errors​

  • 404 NotFound - User not found

Get User's Public Wishlists​

Get a user's public wishlists.

GET /users/:username/wishlists

Authentication​

None required

Path Parameters​

  • username - Username

Response​

{
  "wishlists": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "name": "Summer Reading List",
      "description": "Books to read this summer",
      "isPublic": true,
      "itemCount": 12,
      "createdAt": "2024-03-01T08:00:00Z"
    }
  ]
}

Errors​

  • 404 NotFound - User not found

Get User's Lines​

Get social posts (lines) by a user.

GET /users/:username/lines

Authentication​

None required

Path Parameters​

  • username - Username

Query Parameters​

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

Response​

{
  "items": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "content": "This book completely changed my perspective!",
      "likeCount": 42,
      "replyCount": 8,
      "createdAt": "2024-01-20T14:30:00Z"
    }
  ],
  "nextCursor": "cc0e8400-e29b-41d4-a716-446655440007"
}

Errors​

  • 400 BadRequest - Invalid parameters
  • 404 NotFound - User not found

Get User's Reviews​

Get book reviews by a user.

GET /users/:username/reviews

Authentication​

None required

Path Parameters​

  • username - Username

Query Parameters​

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

Response​

{
  "items": [
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440008",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "rating": 5,
      "content": "An absolute masterpiece of modern literature.",
      "likeCount": 15,
      "createdAt": "2024-01-18T11:00:00Z"
    }
  ],
  "nextCursor": "ee0e8400-e29b-41d4-a716-446655440009"
}

Errors​

  • 400 BadRequest - Invalid parameters
  • 404 NotFound - User not found

Get User's Public Clubs​

Get book clubs a user has joined (public only).

GET /users/:username/clubs

Authentication​

None required

Path Parameters​

  • username - Username

Response​

{
  "clubs": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Science Fiction Book Club",
      "description": "Monthly sci-fi discussions",
      "isPublic": true,
      "memberCount": 24,
      "createdAt": "2024-01-10T12:00:00Z"
    }
  ]
}

Errors​

  • 404 NotFound - User not found

Get User's Public Challenges​

Get reading challenges a user has joined.

GET /users/:username/challenges

Authentication​

None required

Path Parameters​

  • username - Username

Response​

{
  "challenges": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "2024 Reading Challenge",
      "description": "Read 50 books in 2024",
      "goal": 50,
      "participantCount": 152,
      "createdAt": "2023-12-15T10:00:00Z"
    }
  ]
}

Errors​

  • 404 NotFound - User not found