Users

Create and manage ReadRealm user accounts. Look up users by email or ID, update profile details, and delete accounts.

The Users API manages reader accounts. It handles registration, profile retrieval, and account updates. User IDs returned from these endpoints are referenced throughout the Books and Chat APIs for bookmarks, reviews, and messages.

Endpoint summary

Method	Path	Description
POST	/user	Create a new user account
GET	/user	List all users
GET	/user/:email	Find a user by email address
GET	/user/userId/:id	Find a user by ID
GET	/user/profile/:id	Get a user’s profile
PUT	/user/:id	Update a user account
DELETE	/user/:id	Delete a user account

---

POST /user

Registers a new user account.

Passwords are stored as provided. Implement hashing at the application layer before sending to this endpoint.

Request body

username · string · required

Display name for the user.

email · string · required

Email address. Must be a valid email format.

password · string · required

Account password. Maximum 100 characters.

profilePicture · string

URL or base64-encoded image for the user’s avatar. Optional.

curl -X POST http://localhost:3000/user \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "alice",
    "email": "[e-mail]",
    "password": "s3cure-passw0rd"
  }'

Response

_id · string

MongoDB document ID assigned to the new user.

username · string

Display name.

email · string

Email address.

profilePicture · string

Profile picture URL, if provided.

role · string

User role. Defaults to "user".

emailVerifiedAt · string

Timestamp of email verification. null until verified.

---

GET /user

Returns all registered users.

curl http://localhost:3000/user

Response

Array of user objects. Each object contains the fields described in the POST /user response section.

---

GET /user/:email

Looks up a single user by their email address.

The :email segment must be URL-encoded (e.g. alice%40example.com).

Path parameters

email · string · required

URL-encoded email address of the user.

curl 'http://localhost:3000/user/alice%40example.com'

Response

A single user object, or 404 if no user with that email exists.

---

GET /user/userId/:id

Looks up a single user by their MongoDB document ID.

Path parameters

id · string · required

MongoDB _id string of the user.

curl http://localhost:3000/user/userId/64a1f3c2e4b0a1234567890a

Response

A single user object, or 404 if no user with that ID exists.

---

GET /user/profile/:id

Retrieves the public profile for a user by ID. Internally equivalent to GET /user/userId/:id — both resolve using findById.

Path parameters

id · string · required

MongoDB _id string of the user.

curl http://localhost:3000/user/profile/64a1f3c2e4b0a1234567890a

Response

A single user object.

---

PUT /user/:id

Replaces user fields with the provided values. Unspecified fields retain their current values (partial update via PartialType).

Path parameters

id · string · required

MongoDB _id string of the user to update.

Request body

All fields are optional:

username · string

New display name.

email · string

New email address. Must be a valid email format.

password · string

New password. Maximum 100 characters.

profilePicture · string

New profile picture URL or base64 image.

curl -X PUT http://localhost:3000/user/64a1f3c2e4b0a1234567890a \
  -H 'Content-Type: application/json' \
  -d '{"username": "alice_reads"}'

Response

The updated user object.

---

DELETE /user/:id

Permanently deletes a user account.

This operation is irreversible. Bookmarks and reviews authored by this user are not automatically removed.

Path parameters

id · string · required

MongoDB _id string of the user to delete.

curl -X DELETE http://localhost:3000/user/64a1f3c2e4b0a1234567890a

Response

The deleted user document.

---

User object reference

Field	Type	Required	Description
username	string	Yes	Display name
email	string	Yes	Email address
password	string	Yes	Hashed password (max 100 chars)
profilePicture	string	No	Avatar URL or base64 image (max 1000 chars)
role	string	Yes	Account role; defaults to "user"
emailVerifiedAt	Date	No	Timestamp of email verification