Travel-Book API Documentation


To check out the project click on Travel-Book .
Base URL
All API endpoints are accessible via:
https://travelapi.sahilfolio.live
Authentication
Most API endpoints require authentication. Authentication is implemented using JSON Web Tokens (JWT).
To authenticate, include the JWT token in the Authorization header of your request:
Authorization: Bearer <your-access-token>
Error Handling
API responses follow a consistent format:
{
"error": true,
"message": "Error description"
}
Successful responses typically include:
{
"error": false,
"message": "Success message",
// Additional data...
}
API Endpoints
Authentication and User Management
Create Account
Creates a new user account.
URL:
/create-account
Method:
POST
Authentication: Not required
Request Body:
{ "fullName": "John Doe", "email": "john@example.com", "password": "SecurePassword123!" }
Success Response:
{ "error": false, "user": { "fullName": "John Doe", "email": "john@example.com" }, "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "message": "Successfully Registered for a Travel Book!" }
Send Signup OTP
Sends a one-time password (OTP) to verify email during signup.
URL:
/send-signup-otp
Method:
POST
Authentication: Not required
Request Body:
{ "fullName": "John Doe", "email": "john@example.com", "password": "SecurePassword123!" }
Success Response:
{ "error": false, "message": "OTP sent to your email. Please verify to complete registration." }
Verify Signup OTP
Verifies the OTP sent during signup.
URL:
/verify-signup-otp
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com", "otp": "123456" }
Success Response:
{ "error": false, "message": "Account verified successfully!", "user": { "fullName": "John Doe", "email": "john@example.com" }, "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Login
Logs in a user with email and password.
URL:
/login
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com", "password": "SecurePassword123!" }
Success Response:
{ "error": false, "message": "Login Successfully to Travel Book", "user": { "fullName": "John Doe", "email": "john@example.com" }, "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Send Login OTP
Sends an OTP for login verification.
URL:
/send-login-otp
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com" }
Success Response:
{ "error": false, "message": "OTP sent to your email. Please verify to login." }
Verify Login OTP
Verifies the OTP sent for login.
URL:
/verify-login-otp
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com", "otp": "123456" }
Success Response:
{ "error": false, "message": "Login successful!", "user": { "fullName": "John Doe", "email": "john@example.com" }, "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Resend OTP
Resends an OTP for login or signup verification.
URL:
/resend-otp
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com", "isSignup": true // true for signup, false for login }
Success Response:
{ "error": false, "message": "OTP resent to your email." }
Get User
Retrieves authenticated user information.
URL:
/get-user
Method:
GET
Authentication: Required
Success Response:
{ "user": { "fullName": "John Doe", "email": "john@example.com", // Other user fields... }, "message": "" }
Get Profile
Gets detailed user profile with statistics.
URL:
/profile
Method:
GET
Authentication: Required
Success Response:
{ "error": false, "user": { "fullName": "John Doe", "email": "john@example.com", "bio": "Travel enthusiast", // Other profile fields... }, "stats": { "stories": 10, "locations": 5, "favorites": 3 } }
Update Profile
Updates user profile information.
URL:
/update-profile
Method:
PUT
Authentication: Required
Request Body:
{ "fullName": "John Doe", "bio": "Passionate traveler and photographer", "location": "New York, USA", "phone": "+1234567890", "website": "https://johndoe.com", "socialLinks": { "facebook": "https://facebook.com/johndoe", "twitter": "https://twitter.com/johndoe", "instagram": "https://instagram.com/johndoe", "linkedin": "https://linkedin.com/in/johndoe" }, "preferences": { "notificationsEnabled": true, "privacySettings": { "showEmail": false, "showPhone": false, "profileVisibility": "public" }, "theme": "dark" } }
Success Response:
{ "user": { // Updated user object }, "message": "Profile updated successfully" }
Update Profile Image
Updates the user's profile image.
URL:
/update-profile-image
Method:
PUT
Authentication: Required
Request Body: Form data with an image file
image: [file]
Success Response:
{ "profileImage": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/profiles/image.jpg", "message": "Profile image updated successfully" }
Forgot Password
Initiates the password reset process.
URL:
/forgot-password
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com" }
Success Response:
{ "error": false, "message": "Password reset link sent to your email." }
Reset Password
Resets the password using a token.
URL:
/reset-password
Method:
POST
Authentication: Not required
Request Body:
{ "email": "john@example.com", "token": "reset-token-from-email", "newPassword": "NewSecurePassword123!" }
Success Response:
{ "error": false, "message": "Password has been reset successfully. Please log in with your new password." }
Change Password
Changes the password for an authenticated user.
URL:
/change-password
Method:
POST
Authentication: Required
Request Body:
{ "currentPassword": "OldPassword123!", "newPassword": "NewPassword123!" }
Success Response:
{ "error": false, "message": "Password changed successfully" }
Update Privacy Settings
Updates user privacy settings.
URL:
/api/user/privacy-settings
Method:
PATCH
Authentication: Required
Request Body:
{ "profileVisibility": "public" // or "private" }
Success Response:
{ "error": false, "message": "Privacy settings updated successfully", "privacySettings": { "profileVisibility": "public" } }
Travel Stories
Add Travel Story
Creates a new travel story.
URL:
/add-travel-story
Method:
POST
Authentication: Required
Request Body:
{ "title": "My Trip to Paris", "story": "It was an amazing experience visiting the Eiffel Tower...", "visitedLocation": ["Paris, France"], "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/paris.jpg", "visitedDate": "1621458000000" // Timestamp in milliseconds }
Success Response:
{ "story": { // Travel story object }, "message": "Added Successfully" }
Get All Stories
Retrieves all travel stories for the authenticated user.
URL:
/get-all-stories
Method:
GET
Authentication: Required
Success Response:
{ "stories": [ // Array of travel story objects ] }
Edit Travel Story
Updates an existing travel story.
URL:
/edit-story/:id
Method:
PUT
Authentication: Required
URL Parameters:
id
: ID of the travel story to edit
Request Body:
{ "title": "Updated Trip to Paris", "story": "Updated content about my Paris trip...", "visitedLocation": ["Paris, France"], "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/paris_updated.jpg", "visitedDate": "1621458000000" // Timestamp in milliseconds }
Success Response:
{ "story": { // Updated travel story object }, "message": "Update Successful" }
Delete Travel Story
Deletes a travel story.
URL:
/delete-story/:id
Method:
DELETE
Authentication: Required
URL Parameters:
id
: ID of the travel story to delete
Success Response:
{ "message": "Travel Story deleted successfully!" }
Update Favorite Status
Updates the favorite status of a travel story.
URL:
/update-is-favourite/:id
Method:
PUT
Authentication: Required
URL Parameters:
id
: ID of the travel story
Request Body:
{ "isFavourite": true }
Success Response:
{ "story": { // Updated travel story object }, "message": "Update Successful" }
Toggle Profile Visibility
Toggles whether a story is shown on the public profile.
URL:
/toggle-show-on-profile/:id
Method:
PUT
Authentication: Required
URL Parameters:
id
: ID of the travel story
Request Body:
{ "showOnProfile": true }
Success Response:
{ "story": { // Updated travel story object }, "message": "Profile visibility updated successfully" }
Search Stories
Searches travel stories by query text.
URL:
/search
Method:
GET
Authentication: Required
Query Parameters:
query
: Search term
Success Response:
{ "stories": [ // Array of matching travel story objects ] }
Filter Stories by Date Range
Filters travel stories by date range.
URL:
/travel-stories-filter
Method:
GET
Authentication: Required
Query Parameters:
startDate
: Start date (timestamp or ISO string)endDate
: End date (timestamp or ISO string)
Success Response:
{ "stories": [ // Array of filtered travel story objects ] }
Advanced Search
Performs advanced search with multiple filters.
URL:
/advanced-search
Method:
POST
Authentication: Required
Request Body:
{ "location": "Paris", "title": "Trip", "dateRange": { "startDate": "2023-01-01", "endDate": "2023-12-31" }, "isFavourite": true, "sortBy": "newest" // "newest", "oldest", "a-z", "z-a" }
Success Response:
{ "stories": [ // Array of matching travel story objects ], "count": 5, "message": "Search results found" }
Search by Location
Groups and searches travel stories by location.
URL:
/search-by-location
Method:
GET
Authentication: Required
Success Response:
{ "locations": [ { "location": "Paris, France", "count": 3, "previewStory": { // Sample story object for this location } }, // More locations... ], "totalLocations": 5 }
Search by Tags
Searches travel stories by hashtags in content.
URL:
/search-by-tags
Method:
GET
Authentication: Required
Query Parameters:
tags
: Comma-separated list of tags (without #)
Success Response:
{ "stories": [ // Array of matching travel story objects ], "count": 7, "tags": ["paris", "france", "travel"], "message": "Found 7 stories with the specified tags" }
Public API Endpoints
Get Public Story
Retrieves a single travel story by ID for sharing.
URL:
/api/story/:id
Method:
GET
Authentication: Not required
URL Parameters:
id
: ID of the travel story
Success Response:
{ // Travel story object }
Get Public Profile
Retrieves public profile information for a user.
URL:
/api/public-profile/:userId
Method:
GET
Authentication: Not required
URL Parameters:
userId
: ID of the user
Success Response:
{ "error": false, "profile": { // Public user profile data }, "stats": { "stories": 10, "locations": 5, "favorites": 3 }, "recentStories": [ // Array of recent public travel story objects ] }
Get Public Stories
Retrieves public travel stories for a specific user.
URL:
/api/public-stories/:userId
Method:
GET
Authentication: Not required
URL Parameters:
userId
: ID of the user
Query Parameters:
limit
: Number of stories to return (default: 10)page
: Page number for pagination (default: 1)
Success Response:
{ "error": false, "stories": [ // Array of public travel story objects ], "pagination": { "total": 25, "page": 1, "limit": 10, "pages": 3 } }
Image Upload
Upload Image
Uploads an image to be used in travel stories.
URL:
/image-upload
Method:
POST
Authentication: Required
Request Body: Form data with an image file
image: [file]
Success Response:
{ "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/image.jpg" }
System Health
Health Check
Checks if the API is running.
URL:
/health
Method:
GET
Authentication: Not required
Success Response:
OK
Ping
Endpoint for uptime monitoring.
URL:
/ping
Method:
GET
Authentication: Not required
Success Response:
Ping received correctly by backend!!
Data Models
User
{
"fullName": "String (required)",
"email": "String (required, unique)",
"password": "String (hashed, required)",
"createdOn": "Date",
"otp": "String (optional)",
"otpExpiry": "Date (optional)",
"isVerified": "Boolean (default: false)",
"resetPasswordToken": "String (optional)",
"resetPasswordExpiry": "Date (optional)",
"profileImage": "String (URL)",
"bio": "String",
"location": "String",
"phone": "String",
"website": "String",
"socialLinks": {
"facebook": "String",
"twitter": "String",
"instagram": "String",
"linkedin": "String"
},
"preferences": {
"notificationsEnabled": "Boolean",
"privacySettings": {
"showEmail": "Boolean",
"showPhone": "Boolean",
"profileVisibility": "String (enum: 'public', 'private')"
},
"theme": "String (enum: 'light', 'dark', 'system')"
}
}
Travel Story
{
"title": "String (required)",
"story": "String (required)",
"visitedLocation": "Array of Strings",
"isFavourite": "Boolean (default: false)",
"showOnProfile": "Boolean (default: false)",
"userId": "ObjectId (reference to User, required)",
"createdOn": "Date",
"imageUrl": "String (URL, required)",
"visitedDate": "Date (required)"
}
Rate Limiting and Usage
The API currently does not impose strict rate limits, but excessive requests may be throttled to ensure service stability. Please use the API responsibly.
🚀 Deployment
Frontend:
travelbook.sahilfolio.live
Backend:
travelapi.sahilfolio.live
Support and Feedback
For support or feedback regarding the API, please contact the developer at the email contact@sahilfolio.live
For more information or to connect with me, feel free to check out my portfolio, GitHub, LinkedIn, and Twitter:
Portfolio: sahilfolio.live
GitHub: Sahilll94
LinkedIn: sahilll94
Twitter: Sa_hilll94
Instagram: sa_hilll94
Hashnode: Sahilll94
© 2025 Travel Book API. All rights reserved.
Subscribe to my newsletter
Read articles from Sahil directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by

Sahil
Sahil
I’m a passionate third-year BTech student pursuing Computer Science and Engineering at SRM Institute of Science and Technology, Chennai. Currently, I’m deep diving into Data Structures & Algorithms (DSA) and working with the MERN stack, focusing on building scalable web applications.