Natours is a RESTful API for managing tours, users, reviews, and authentication.
It supports role-based access control (User / Admin) and JWT authentication.
{{URL}}/api/v1\n\nNatours uses JWT (Bearer Token) authentication.
\nAuthorization: Bearer {{jwt}}\n\nToken is returned on login / signup
\nRequired for protected routes
\nAdmin-only routes require role: admin
POST /users/signup – Create new user
POST /users/login – Login user
POST /users/forgotPassword
PATCH /users/resetPassword/:token
PATCH /users/updateMyPassword
GET /users/me – Get current user
PATCH /users/updateMe – Update own data
DELETE /users/deleteMe – Deactivate own account
GET /users – Get all users
GET /users/:id – Get user by ID
PATCH /users/:id – Update user
DELETE /users/:id – Delete user
GET /tours – Get all tours
GET /tours/:id – Get tour by ID
POST /tours – Create tour
PATCH /tours/:id – Update tour
DELETE /tours/:id – Delete tour
GET /tours/top-5-cheap
GET /tours/tour-stats
GET /tours/monthly-plan/:year
GET /tours-within/:distance/center/:latlng/unit/:unit
GET /tours/distances/:latlng/unit/:unit
Reviews are nested under tours.
\nGET /tours/:tourId/reviews – Get tour reviews
POST /tours/:tourId/reviews – Create review (User)
Admin:
\nGET /reviews
DELETE /reviews/:id
{\n \"status\": \"success\",\n \"data\": {\n \"data\": {}\n }\n}\n\n{\n \"status\": \"fail\",\n \"message\": \"Error description\"\n}\n\nUses MongoDB with Mongoose
\nUses REST best practices
\nSupports filtering, sorting, pagination, and field limiting
\nDesigned for learning real-world backend architecture
\nNatours is a learning-focused backend project demonstrating:
\nAuthentication & Authorization
\nREST API design
\nRole-based access control
\nReal-world data modeling
\nNatours API – Backend Project
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Tour Booking App API Documentation","slug":"tour-booking-app-api-documentation"}],"owner":"46789817","collectionId":"7aa36c99-ceec-4c08-b4a9-c5243ff12398","publishedId":"2sBXVifpK4","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-01-17T22:50:59.000Z"},"item":[{"name":"Authetntication","item":[{"name":"Sign Up","id":"23808b45-185c-4469-a7fe-a20c0ba04a87","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"name\": \"defulalt\",\r\n \"email\": \"defulalt@example.com\",\r\n \"password\": \"{{password}}\",\r\n \"passwordConfirm\": \"{{password}}\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/signup","description":"This endpoint allows new users to register and create an account in the Natours application. Upon successful registration, the user receives a JWT token for authentication in subsequent requests.
\nMethod: POST
Endpoint: {{URL}}api/v1/users/signup
The request body must be sent as raw JSON with the following required fields:
\n{\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"password\": \"{{password}}\",\n \"passwordConfirm\": \"{{password}}\"\n}\n\nUpon successful registration, the endpoint returns a 201 Created status code with the following response structure:
{\n \"status\": \"success\",\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"data\": {\n \"user\": {\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"active\": true,\n \"_id\": \"696c0662b4e8fa3998f39ade\",\n \"__v\": 0\n }\n }\n}\n\nstatus: Indicates the success or failure of the request
\ntoken: JWT authentication token to be used for protected routes
\ndata.user: The newly created user object containing:
\nname: User's name
email: User's email
role: User role (default: \"user\")
active: Account status
_id: Unique user identifier
__v: Version key
{{URL}}: Base URL for the API (defined in environment)
\n{{password}}: Password value (defined in environment for testing purposes)
\nThe JWT token returned in the response should be saved and used for authentication in subsequent API requests
\nPasswords must match between password and passwordConfirm fields
Email addresses must be unique across the system
\nThe token can be stored in an environment variable for use in other requests
\nThis endpoint authenticates a user by validating their email and password credentials. Upon successful authentication, it returns a JWT (JSON Web Token) that can be used for subsequent authenticated requests throughout the application.
\nPOST
{{URL}}api/v1/users/login\n\nThe request requires a JSON payload with the following fields:
\nExample Request Body:
\n{\n \"email\": \"tester@test.com\",\n \"password\": \"{{password}}\"\n}\n\nThis endpoint does not require authentication. It is a public endpoint used to obtain authentication credentials (JWT token) for subsequent API calls.
\n{\n \"status\": \"success\",\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"data\": {\n \"user\": {\n \"_id\": \"696c0662b4e8fa3998f39ade\",\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"__v\": 0\n }\n }\n}\n\nThis request includes an automated post-response script that extracts the JWT token from the response and stores it in the environment variable jwt:
pm.environment.set(\"jwt\", pm.response.json().token);\n\nWhat this means:
\nAfter a successful login, the JWT token is automatically saved to your active environment
\nThe {{jwt}} variable can be used in subsequent requests for authentication
No manual copying of the token is required
\nEnvironment Variables: This request uses two environment variables:
\n{{URL}} - Base API URL (e.g., http://localhost:3000/ or https://api.natours.com/)
{{password}} - User password (stored securely in environment)
Workflow:
\nSend this request with valid credentials
\nThe JWT token is automatically saved to the environment
\nUse the saved token in the Authorization header of protected endpoints
\nToken Expiration: JWT tokens typically have an expiration time. If you receive authentication errors on other endpoints, try logging in again to refresh the token.
\nSecurity Best Practice: Store sensitive data like passwords in environment variables rather than hardcoding them in the request body.
\nThis endpoint initiates the password reset process by sending a reset token to the user's registered email address.
\n{{URL}}api/v1/users/forgotPasswordExample Request Body:
\n{\n \"email\": \"tester@test.com\"\n}\nSuccess Response (200 OK):
\n{\n \"status\": \"success\",\n \"message\": \"token sent to email\"\n}\nThis endpoint allows authenticated users to update their own password. After a successful password change, a new JWT token is issued and the user's passwordChangedAt timestamp is updated.
Required: Yes
This endpoint requires a valid JWT token. Include the token in the Authorization header:
Authorization: Bearer {{jwt}}\n\n{\n \"passowrdCurrent\": \"{{password}}\",\n \"password\": \"newSecurePassword123\",\n \"passwordConfirm\": \"newSecurePassword123\"\n}\n\nReturns a new JWT token and the updated user data.
\n{\n \"status\": \"success\",\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"data\": {\n \"user\": {\n \"_id\": \"696d42f6036855cb4a45d77c\",\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"__v\": 0,\n \"passwordChangedAt\": \"2026-01-18T20:31:55.104Z\"\n }\n }\n}\n\n⚠️ Field Name Typo: The request body uses passowrdCurrent (missing 'w') instead of passwordCurrent. Ensure you use the exact spelling when making requests.
🔄 Token Update: A new JWT token is automatically generated and saved to the environment variable jwt via the post-response script.
🔒 Security: The current password must be provided to verify the user's identity before allowing the password change.
\n✅ Password Matching: The password and passwordConfirm fields must match, or the request will fail.
📅 Timestamp: The passwordChangedAt field is automatically updated to the current timestamp upon successful password change.
User-initiated password changes from account settings
\nPeriodic password rotation for security compliance
\nPassword updates after a security incident
\nThis endpoint allows users to reset their password using a valid reset token. The reset token is obtained by first calling the Forgot Password endpoint, which sends a password reset email containing the token.
\nPATCH {{URL}}api/v1/users/resetPassword/:token\n\n1cf05f0c9797e95d087d392bb5a11b6e1c8a6b59bc8fee3e244397a1cdd93699The request body must be in JSON format and include the following fields:
\n{\n \"password\": \"newSecurePassword123\",\n \"passwordConfirm\": \"newSecurePassword123\"\n}\n\nUpon successful password reset, the endpoint returns:
\n{\n \"status\": \"success\",\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"data\": {\n \"user\": {\n \"_id\": \"696d42f6036855cb4a45d77c\",\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"__v\": 0,\n \"passwordChangedAt\": \"2026-01-18T20:40:25.959Z\"\n }\n }\n}\n\nstatus: Indicates the success of the operation
\ntoken: A new JWT (JSON Web Token) for authenticating subsequent requests
\ndata.user: The updated user object including:
\n_id: User's unique identifier
name: User's name
email: User's email address
role: User's role in the system
passwordChangedAt: Timestamp of when the password was last changed
This request includes an automated script that runs after receiving a successful response:
\npm.environment.set(\"jwt\", pm.response.json().token);\n\nWhat it does: Automatically extracts the JWT token from the response and saves it to the active environment variable jwt. This allows subsequent authenticated requests to use the new token without manual copying.
Call Forgot Password first: Before using this endpoint, you must call the \"Forgot Password\" endpoint with the user's email address
\nCheck email: Retrieve the reset token from the password reset email
\nToken validity: Reset tokens typically expire after a certain period (e.g., 10 minutes). Ensure you use the token before it expires
\nThe password and passwordConfirm fields must match exactly, or the request will fail
After a successful password reset, the user is automatically logged in (JWT token is provided)
\nThe reset token can only be used once. After a successful reset, the token becomes invalid
\nIf the token is invalid or expired, you'll need to request a new one via the Forgot Password endpoint
\nCommon error scenarios:
\n400 Bad Request: Password and passwordConfirm don't match, or password doesn't meet requirements
\n400 Bad Request: Token is invalid or has expired
\n404 Not Found: No user found with the provided token
\nThis endpoint performs a soft delete operation on the currently authenticated user's account. Instead of permanently removing the user and their data from the database, it marks the account as inactive, preserving all user data for potential recovery or audit purposes.
\nRequired: JWT Bearer Token
\nThis endpoint requires authentication via a valid JWT token. The token must be included in the request headers:
\nHeader: Authorization
Value: Bearer {{jwt}}
The user to be deactivated is identified from the JWT token payload.
\nMethod: DELETE
URL: {{URL}}api/v1/users/deleteMe
Full URL Example: https://api.example.com/api/v1/users/deleteMe
When this endpoint is called:
\nThe system identifies the user from the provided JWT token
\nThe user's account is marked as inactive/deleted in the database
\nThe user's data is preserved in the system
\nThe user will no longer be able to log in or access protected resources
\nThe account can potentially be reactivated by an administrator
\nStatus Code: 204 No Content (typical for successful DELETE operations)
Response Body: Empty or minimal success message
\n⚠️ This is a SOFT DELETE operation:
\nUser data is NOT permanently removed from the database
\nThe account is marked as inactive but remains in the system
\nThis approach allows for data recovery and maintains referential integrity
\nUser-generated content (reviews, bookings, etc.) remains associated with the account
\nAn administrator may be able to reactivate the account if needed
\n🔒 Security Considerations:
\nOnly the authenticated user can delete their own account
\nThe JWT token determines which account will be deactivated
\nOnce deactivated, the same JWT token will no longer grant access to protected resources
\nThis endpoint retrieves all tours from the database that match the specified filter criteria. It allows you to query tours based on price ranges and minimum rating requirements.
\nThe following query parameters are used to filter the tour results:
\nprice[lt]Type: Number
\nValue: 1000
Description: Filters tours with a price less than 1000 (currency units)
\nOperator: lt (less than)
ratingsAverage[gte]Type: Number
\nValue: 4.7
Description: Filters tours with an average rating greater than or equal to 4.7
\nOperator: gte (greater than or equal)
The API returns a list of tour objects that satisfy both filter conditions:
\nTours with price < 1000
\nTours with ratingsAverage ≥ 4.7
\nResponse Format:
\n{\n \"status\": \"success\",\n \"results\": <number of tours>,\n \"data\": {\n \"tours\": [\n {\n \"id\": \"...\",\n \"name\": \"...\",\n \"price\": <number less than 1000>,\n \"ratingsAverage\": <number >= 4.7>,\n \"duration\": \"...\",\n \"maxGroupSize\": \"...\",\n \"difficulty\": \"...\",\n ...\n }\n ]\n }\n}\n\nThis endpoint uses MongoDB-style query operators for advanced filtering:
\nComparison Operators:
\n[lt] - Less than
[lte] - Less than or equal
[gt] - Greater than
[gte] - Greater than or equal
[eq] - Equal to
[ne] - Not equal to
Multiple Filters: When multiple query parameters are provided, they are combined with an AND logic (all conditions must be met)
\nAll filters are applied server-side for optimal performance
\nThe filtering mechanism supports any numeric or comparable field in the tour schema
\nResults are returned in the default sort order unless a sort parameter is specified
\nRetrieves detailed information about a specific tour using its unique identifier. This endpoint returns comprehensive tour data including itinerary, pricing, ratings, guides, and customer reviews.
\nMethod: GET
Endpoint: {{URL}}api/v1/tours/:tourId
Example: {{URL}}api/v1/tours/5c88fa8cf4afda39709c2955
The response returns a JSON object with the following structure:
\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n // Tour object with detailed information\n }\n }\n}\n\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"_id\": \"5c88fa8cf4afda39709c2955\",\n \"name\": \"The Sea Explorer\",\n \"duration\": 7,\n \"maxGroupSize\": 15,\n \"difficulty\": \"medium\",\n \"ratingsAverage\": 4.8,\n \"ratingsQuantity\": 6,\n \"price\": 497,\n \"summary\": \"Exploring the jaw-dropping US east coast by foot and by boat\",\n \"startLocation\": {\n \"type\": \"Point\",\n \"coordinates\": [-80.185942, 25.774772],\n \"address\": \"301 Biscayne Blvd, Miami, FL 33132, USA\",\n \"description\": \"Miami, USA\"\n },\n \"locations\": [\n {\n \"type\": \"Point\",\n \"coordinates\": [-80.128473, 25.781842],\n \"description\": \"Lummus Park Beach\",\n \"day\": 1\n }\n ],\n \"guides\": [\n {\n \"_id\": \"5c8a22c62f8fb814b56fa18b\",\n \"name\": \"Miyah Myles\",\n \"email\": \"miyah@example.com\",\n \"role\": \"lead-guide\"\n }\n ],\n \"reviews\": [\n {\n \"_id\": \"5c8a34ed14eb5c17645c9108\",\n \"review\": \"Amazing experience!\",\n \"rating\": 5,\n \"user\": {\n \"name\": \"Lourdes Browning\",\n \"photo\": \"user-2.jpg\"\n }\n }\n ]\n }\n }\n}\n\nGeoJSON Format: Location data uses GeoJSON Point format with longitude/latitude coordinates
\nPopulated Data: The response includes populated references to guides and reviews with full user details
\nImage References: Image fields contain filenames that should be resolved to full URLs on the client side
\nDate Format: All dates are in ISO 8601 format (e.g., 2026-06-19T09:00:00.000Z)
Calculated Fields: Some fields like durationWeek are virtual properties calculated from other fields
Reviews: Reviews are embedded with user information and sorted by creation date
\nDisplay detailed tour information on tour detail pages
\nShow tour itinerary with location markers on maps
\nPresent guide information and customer reviews
\nEnable booking functionality with available start dates
\nCalculate and display tour metrics (ratings, duration, price)
\nThis endpoint retrieves aggregated statistics about tour starts per month for a specific year. It provides a comprehensive overview of tour scheduling and distribution throughout the year.
\nReturns monthly tour planning data, including the number of tour starts and the names of tours scheduled for each month in the specified year.
\nThe endpoint returns a JSON object with the following structure:
\n{\n \"status\": \"success\",\n \"data\": {\n \"plan\": [\n {\n \"numTourStarts\": 3,\n \"tours\": [\"The Snow Adventurer\", \"The Star Gazer\", \"The Northern Lights\"],\n \"month\": 1\n }\n ]\n }\n}\n\nResponse Fields:
\nstatus: Indicates the success or failure of the request
data.plan: Array of monthly tour statistics
numTourStarts: Number of tours starting in that month
tours: Array of tour names scheduled for that month
month: Month number (1-12)
The response only includes months that have scheduled tour starts
\nMonths without any tour starts will not appear in the response array
\nTour names are returned as an array, allowing multiple tours per month
\nThe plan array is not necessarily sorted by month number
\nThis endpoint retrieves aggregated statistics for all tours in the system, grouped by their difficulty level. It provides valuable insights into tour distribution, pricing, and ratings across different difficulty categories.
\nThe endpoint returns a success response containing a stats array. Each object in the array represents statistics for a specific difficulty level.
This endpoint is useful for:
\nDisplaying tour statistics on a dashboard or analytics page
\nHelping users understand the distribution of tours by difficulty
\nComparing pricing and ratings across different difficulty levels
\nMaking data-driven decisions about tour offerings
\n⚠️ Note: This request requires the {{URL}} environment variable to be set with your API base URL (e.g., https://api.natours.com/)
{\n \"status\": \"success\",\n \"data\": {\n \"stats\": [\n {\n \"_id\": \"EASY\",\n \"numTours\": 4,\n \"numRatings\": 21,\n \"avgRating\": 4.7,\n \"avgPrice\": 872,\n \"minPrice\": 397,\n \"maxPrice\": 997\n }\n ]\n }\n}\n\nThis endpoint retrieves the top 5 cheapest tours from the database, providing a curated list of budget-friendly tour options with the best ratings.
\n{{URL}}api/v1/tours/top-5-cheapThis endpoint returns a pre-filtered and sorted list of tours optimized for users looking for affordable, highly-rated tour options. The results are:
\nThe response returns tour documents with the following fields:
\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": [\n {\n \"name\": \"Tour Name\",\n \"price\": 299,\n \"ratingsAverage\": 4.8,\n \"summary\": \"Tour summary\",\n \"difficulty\": \"easy\",\n \"guides\": [...]\n }\n ]\n }\n}\nThis endpoint calculates the distance from a specific geographic point (latitude/longitude coordinates) to all available tours in the system. It returns a sorted list of tours with their calculated distances, making it useful for finding nearby tours or determining travel requirements.
\nFormat: longitude,latitude
Example: -117.68027936629767,33.578014746144014
Format: /unit/{unit}
Options:
mi - Mileskm - KilometersSpecifies the unit of measurement for the returned distances.
\nThe endpoint returns a JSON object with the following structure:
\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": [\n {\n \"_id\": \"tour_id\",\n \"name\": \"Tour Name\",\n \"distance\": 71.03\n }\n ]\n }\n}\nResponse Fields:
\n_id: Unique identifier for the tourname: Name of the tourdistance: Calculated distance from the specified point in the requested unitTours are typically returned sorted by distance (closest first).
\nA travel booking application wants to show users which tours are closest to their current location in Los Angeles, CA (coordinates: -117.68, 33.58). By calling this endpoint with their coordinates and specifying miles as the unit, the app can display a list like:
\nThis helps users make informed decisions about which tours are most accessible from their location.
\n","urlObject":{"path":["v1","tours","distances","-117.68027936629767,33.578014746144014","unit","mi"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"864bae3a-2636-465d-bda0-669187d5f363"},{"name":"Get Tours Within Radius","id":"8eb7c9c5-35ab-49f9-a45e-bb8d32a776eb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours/tours-within/2000/center/-117.32324032947227, 52.37559917665913/unit/mi","description":"This endpoint retrieves all tours that fall within a specified radius from a given center point. It uses geospatial queries to find tours based on their starting location, making it ideal for location-based tour discovery.
\nThe endpoint uses the following path parameters in the format:/tours-within/:distance/center/:coordinates/unit/:unit
Parameter: distance (e.g., 2000)
Description: The radius distance from the center point
\nType: Number
\nExample: 2000 means search within 2000 units from the center
Parameter: coordinates (e.g., -117.32324032947227, 52.37559917665913)
Description: The latitude and longitude of the center point for the search
\nFormat: longitude, latitude (comma-separated)
Example: -117.32324032947227, 52.37559917665913
Note: Coordinates should be provided as longitude first, then latitude
\nParameter: unit (e.g., mi)
Description: The unit of measurement for the distance
\nAccepted Values:
\nmi - Miles
km - Kilometers
Example: mi for miles
{\n \"status\": \"success\",\n \"result\": 7,\n \"data\": {\n \"data\": [\n {\n \"_id\": \"tour_id\",\n \"name\": \"Tour Name\",\n \"duration\": 5,\n \"maxGroupSize\": 8,\n \"difficulty\": \"easy\",\n \"ratingsAverage\": 4.4,\n \"ratingsQuantity\": 7,\n \"price\": 1997,\n \"summary\": \"Brief tour description\",\n \"description\": \"Detailed tour description\",\n \"imageCover\": \"tour-image.jpg\",\n \"images\": [\"image1.jpg\", \"image2.jpg\"],\n \"startDates\": [\"2026-04-14T09:00:00.000Z\"],\n \"startLocation\": {\n \"type\": \"Point\",\n \"coordinates\": [-122.29286, 38.294065],\n \"address\": \"Full address\",\n \"description\": \"Location description\"\n },\n \"locations\": [...],\n \"guides\": [...]\n }\n ]\n }\n}\n\nstatus: Request status (success)
result: Number of tours found within the specified radius
\ndata.data: Array of tour objects containing:
\nBasic info: name, duration, difficulty, price
\nRatings: ratingsAverage, ratingsQuantity
\nMedia: imageCover, images array
\nLocations: startLocation with coordinates and address
\nAdditional details: guides, locations, start dates
\nScenario: A user in Manitoba, Canada wants to find all available tours within 2000 miles of their location.
\nRequest:
\nGET {{URL}}api/v1/tours/tours-within/2000/center/-117.32324032947227,52.37559917665913/unit/mi\n\nResult: Returns 7 tours including \"The Wine Taster\" in California, \"The Park Camper\" in Las Vegas, \"The Sports Lover\" in Malibu, and others that fall within the 2000-mile radius from the specified coordinates.
\nThis is particularly useful for:
\nTravel planning applications showing nearby tours
\nMobile apps with location-based tour recommendations
\nRegional tour discovery features
\nDistance-based tour filtering
\nCreates a new tour in the system with the specified details including duration, pricing, difficulty level, and other tour-specific information.
\nMethod: POST
URL: {{URL}}api/v1/tours
This endpoint requires authentication using a JWT token. The token should be included in the request headers.
\nRequired Variable: {{jwt}}
The request body should be in JSON format with the following schema:
\n{\n \"name\": \"New Test Tour\",\n \"duration\": 5,\n \"maxGroupSize\": 25,\n \"difficulty\": \"easy\",\n \"price\": 397,\n \"secrateTour\": false,\n \"summary\": \"Test doc\",\n \"imageCover\": \"tour-1-cover.jpg\"\n}\n\nWhen a tour is successfully created, the API returns a 201 Created status with the complete tour object including system-generated fields.
Response Structure:
\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"name\": \"New Test Tour\",\n \"duration\": 5,\n \"maxGroupSize\": 25,\n \"difficulty\": \"easy\",\n \"ratingsAverage\": 4.5,\n \"ratingsQuantity\": 0,\n \"price\": 397,\n \"summary\": \"Test doc\",\n \"imageCover\": \"tour-1-cover.jpg\",\n \"images\": [],\n \"startDates\": [],\n \"secrateTour\": false,\n \"guides\": [],\n \"_id\": \"696adfa22ebd9af633b97bee\",\n \"createdAt\": \"2026-01-17T01:02:26.046Z\",\n \"locations\": [],\n \"slug\": \"new-test-tour\",\n \"__v\": 0,\n \"durationWeek\": 0.7142857142857143,\n \"id\": \"696adfa22ebd9af633b97bee\"\n }\n }\n}\n\nThe response includes all submitted fields plus additional system-generated fields:
\n_id / id: Unique identifier for the tour
createdAt: Timestamp when the tour was created
slug: URL-friendly version of the tour name
ratingsAverage: Average rating (default: 4.5)
ratingsQuantity: Number of ratings (default: 0)
durationWeek: Duration converted to weeks
images: Array of additional tour images
startDates: Array of tour start dates
guides: Array of tour guides
locations: Array of tour locations
__v: Version key (MongoDB)
Ensure all required fields are provided in the request body
\nThe {{URL}} variable should point to your API base URL
The tour slug is automatically generated from the tour name
\nDefault ratings are initialized when a tour is created
\nDuration in weeks is automatically calculated from the duration in days
\nReturns data for the currently authenticated user (signed in or just signed up).
\nGET
\n{{URL}}/api/v1/users/me\n\nRequires a valid Bearer Token.
\nAuthorization: Bearer {{jwt}}\n\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"_id\": \"696c0662b4e8fa3998f39ade\",\n \"name\": \"tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"__v\": 0,\n \"passwordResetExpires\": \"2026-01-17T22:15:57.392Z\",\n \"passwordResetToken\": \"afd705504438fb9cb36fbf6d300e6ff36e8d2641e64fccf5a74251affc5666e7\"\n }\n }\n}\n\nReturns the currently logged-in user
\nUser is identified from the JWT
\nSensitive fields may be hidden depending on backend settings
\nReturns 401 Unauthorized if token is missing or invalid
\nUpdates user data by ID.
This action is restricted to admin users only.
PATCH
\n{{URL}}/api/v1/users/:userId\n\nAdmin authorization required.
\nAuthorization: Bearer {{jwt}}\n\nuserId → ID of the user to be updatedExample:
\n696c0662b4e8fa3998f39ade\n\nSend only the fields you want to update.
\n{\n \"name\": \"Updated Name\",\n \"role\": \"user\"\n}\n\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"_id\": \"696c0662b4e8fa3998f39ade\",\n \"name\": \"Updated Name\",\n \"role\": \"user\"\n }\n }\n}\n\nOnly users with admin role can access this endpoint
\nSend partial data (PATCH)
\nSensitive fields may be restricted by backend
\nReturns 403 Forbidden if user is not admin
\nReturns 404 if user does not exist
\nThis endpoint allows the currently authenticated user to update their own profile data. It provides a secure way for users to modify their account information without requiring administrator privileges.
\nRequired: JWT Bearer Token
\nThe request must include a valid JWT token in the Authorization header. The token identifies the user whose data will be updated.
\nPATCH {{URL}}api/v1/users/updateMe\n\nThe following fields can be updated through this endpoint:
\nContent-Type: application/json
{\n \"name\": \"Better Tester\"\n}\n\n{\n \"status\": \"success\",\n \"data\": {\n \"user\": {\n \"_id\": \"696d42f6036855cb4a45d77c\",\n \"name\": \"Better Tester\",\n \"email\": \"tester@test.com\",\n \"role\": \"user\",\n \"__v\": 0,\n \"passwordChangedAt\": \"2026-01-18T20:40:25.959Z\"\n }\n }\n}\n\nThe response includes the complete updated user object with all current field values.
\n⚠️ Password Updates: This endpoint should NOT be used to update passwords. Use the dedicated \"Update My Password\" endpoint instead for password changes.
\n⚠️ Email Updates: Depending on your API implementation, email changes may require additional verification steps and might not be allowed through this endpoint.
\n⚠️ Role Changes: Users cannot change their own role through this endpoint. Role modifications require administrator access.
\n✅ Authentication Required: Only authenticated users can update their own data. The JWT token determines which user's data is updated.
\n✅ Self-Service Only: Users can only update their own profile data, not other users' data.
\nDeletes a user by ID.
This action is restricted to admin users only.
DELETE
\n{{URL}}/api/v1/users/:userId\n\nAdmin authorization required.
\nAuthorization: Bearer {{jwt}}\n\nuserId → ID of the user to be deletedExample:
\n696c0662b4e8fa3998f39ade\n\nNo content is returned.
\nOnly users with admin role can access this endpoint
\nAction is irreversible
\nReturns 403 Forbidden if user is not admin
\nReturns 404 if user does not exist
\nRetrieves all reviews associated with a specific tour. This endpoint returns a paginated list of reviews including user feedback, ratings, and metadata for the specified tour.
\nGET {{URL}}api/v1/tours/:tourId/reviews\n\nURL - Base URL for the API (e.g., https://api.natours.com/)
jwt - JSON Web Token for authentication
This endpoint requires authentication via Bearer token. The JWT token should be included in the Authorization header:
\nAuthorization: Bearer {{jwt}}\n\nReturns a JSON object containing:
\nstatus - Request status (\"success\")
data - Object containing review data and MongoDB query execution details
Review documents with user information, ratings, and comments
\nQuery execution statistics and performance metrics
\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"queryPlanner\": { ... },\n \"executionStats\": { ... }\n }\n }\n}\n\nFetch all reviews for a specific tour to display on the tour detail page, allowing potential customers to read feedback from previous participants before booking.
\nThe response includes MongoDB query execution details which can be useful for performance monitoring and optimization
\nReviews are sorted by creation date in descending order (newest first)
\nDefault limit is 100 reviews per request
\nCreates a review for a specific tour by the authenticated user.
\nPOST
\n{{URL}}/api/v1/tours/:tourId/reviews\n\nRequires a Bearer Token:
\nAuthorization: Bearer {{jwt}}\n\n{\n \"rating\": 5,\n \"review\": \"perfect\"\n}\n\n{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"review\": \"perfect\",\n \"rating\": 5,\n \"tour\": \"5c88fa8cf4afda39709c2955\",\n \"user\": \"696c0662b4e8fa3998f39ade\",\n \"_id\": \"696c0846b4e8fa3998f39ae7\",\n \"createdAt\": \"2026-01-17T22:08:06.171Z\"\n }\n }\n}\n\nUser is taken automatically from JWT
\nTour ID comes from the URL
\nOne review per user per tour (usually enforced by backend)
\nEndFragment
\n","urlObject":{"path":["v1","tours","5c88fa8cf4afda39709c2955","reviews"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"7e32596d-71b1-4304-b5ed-731f4c208fc9"}],"id":"24df4bfd-06f9-4b1f-842e-706ec0c91207","_postman_id":"24df4bfd-06f9-4b1f-842e-706ec0c91207","description":""}],"variable":[{"key":"baseURL","value":"","type":"default"}]}