The Natours API contains endpoints for Tours, Users, and Reviews
The Natours API is a full-featured RESTful backend for a tour booking application. It covers the complete lifecycle of a tour platform — from browsing and booking tours to writing reviews and managing user accounts — and is organized into six focused resource folders.
Core CRUD operations for tour resources, plus specialized endpoints for aggregation (statistics, monthly planning, top-5 cheap tours) and geospatial queries (find tours within a radius, calculate distances from a point). Also includes utility requests for testing error handling and HTTP Parameter Pollution (HPP) protection.
\nFull CRUD lifecycle for user-submitted tour reviews via the top-level /api/v1/reviews route — get, create, update, and delete reviews across all tours.
Nested review endpoints scoped to a specific tour (/api/v1/tours/:tourId/reviews). Use these to retrieve or create reviews in the context of a parent tour resource.
Admin-level user management (list, fetch, update, delete any user) alongside self-service endpoints that let the currently authenticated user view, update, or deactivate their own account.
\nAll identity and account-security flows: sign up, log in, forgot password, reset password (via emailed token), and update password for an already-authenticated user. JWT-based authentication is used throughout the API.
\nTour booking management, including initiating a Stripe checkout session for a tour, retrieving all bookings (admin only), and fetching a single booking by ID.
\nBase URL: {{URL}}api/v1
Auth: JWT Bearer token — store your token in the {{jwt}} environment variable after logging in.
Retrieves a list of all available tours. Supports advanced filtering, sorting, field limiting, and pagination via query parameters.
\nThis endpoint does not require authentication. An Authorization header with a Bearer token may be provided to access protected tour data if applicable.
Returns a JSON object with a status field and a data object containing an array of tour documents.
Query for tour duration.Supports gte,lte,gt,It operators.
\n","type":"text/plain"},"key":"duration","value":"7"},{"disabled":true,"key":"duration","value":"9"},{"disabled":true,"key":"price[lt]","value":"1000"},{"disabled":true,"key":"ratingsAverage[gte]","value":"4.7"}],"variable":[]}},"response":[],"_postman_id":"927d2fd6-b69b-4b1e-bb5d-71532cd07db4"},{"name":"Get Tour","id":"b3aa2797-3305-462f-b8c7-284c3a9433bb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{URL}}api/v1/tours/5c88fa8cf4afda39709c2961","description":"Retrieves the details of a single tour by its unique ID.
\nGET {{URL}}api/v1/tours/:id
No authentication is required for this endpoint.
\nReturns a JSON object containing the full details of the requested tour, including fields such as name, duration, difficulty, price, summary, description, and more.
\n{\n \"status\": \"success\",\n \"data\": {\n \"tour\": {\n \"_id\": \"5c88fa8cf4afda39709c2961\",\n \"name\": \"The Forest Hiker\",\n \"duration\": 5,\n \"maxGroupSize\": 25,\n \"difficulty\": \"easy\",\n \"price\": 397,\n \"summary\": \"Breathtaking hike through the Canadian Banff National Park\",\n ...\n }\n }\n}\nCreates a new tour in the Natours database. This endpoint requires authentication with a valid JWT token.
\nSend a JSON object with the following fields:
\n{\n \"name\": \"New Test Tour\",\n \"duration\": 1,\n \"maxGroupSize\": 1,\n \"difficulty\": \"easy\",\n \"price\": 200,\n \"summary\": \"Test tour\",\n \"imageCover\": \"tour-3-cover.jpg\"\n}\nThis request uses a Bearer token passed via the Authorization header. The {{jwt}} environment variable must be set with a valid token.
Updates an existing tour by its ID using a PATCH request. This endpoint supports partial updates — only the fields provided in the request body will be updated.
This request requires a valid JWT token. The token is read from the {{jwt}} variable (set in your active environment). Ensure the jwt variable is populated before sending this request.
The request body uses multipart/form-data encoding.
\n\nNote: At least one field should be provided for a meaningful update.
\n
On success, the endpoint returns a 200 OK response containing the updated tour object with all current field values reflected.
Permanently deletes a specific tour from the database by its unique ID.
\nDELETE {{URL}}api/v1/tours/:id\nThe tour ID is embedded directly in the URL path. In this request, the tour with ID 5c88fa8cf4afda39709c295a will be deleted.
This endpoint requires JWT authentication. The jwt variable must be set in the active environment and passed as a Bearer token in the Authorization header. Requests without a valid token will be rejected with a 401 Unauthorized response.
admin or lead-guide) are authorized to perform this action.URL environment variable is set to the correct base URL (e.g., http://localhost:3000/ or the production URL) before sending this request.Demonstrates how the Natours API handles routes with multiple optional URL path parameters. This request is used as a learning/testing exercise to explore how Express.js can be configured to accept optional route segments.
\nGET {{URL}}api/v1/tours/5/23\nThis request illustrates how Express routes can be defined with optional parameters using the ? modifier in the route definition. For example:
router.get('/:id/:x?/:y?', tourController.getTour);\nWith this pattern:
\n:id is required:x and :y are optional — the route will still match even if they are omittedThis is useful when you want a single route handler to accommodate varying levels of specificity in the URL without defining multiple separate routes.
\nRetrieves the top 5 cheapest tours available in the Natours API. This is a pre-aliased route that automatically applies sorting by price (ascending) and limits the results to 5 tours — no additional query parameters are needed.
\nThis route is a convenience alias for the following query:
\nGET {{URL}}api/v1/tours?sort=price&limit=5\nThe server pre-configures the query middleware to:
\nprice in ascending order (cheapest first)🔓 No authentication required. This endpoint is publicly accessible.
\nNone. No query parameters, headers, or request body are needed.
\nStatus: 200 OK
Returns a JSON object containing a list of up to 5 tour objects, sorted from cheapest to most expensive.
\n{\n \"status\": \"success\",\n \"results\": 5,\n \"data\": {\n \"tours\": [\n {\n \"name\": \"The Sea Explorer\",\n \"duration\": 7,\n \"maxGroupSize\": 15,\n \"difficulty\": \"medium\",\n \"ratingsAverage\": 4.8,\n \"price\": 497,\n ...\n },\n ...\n ]\n }\n}\nEach tour object typically includes fields such as name, duration, maxGroupSize, difficulty, ratingsAverage, ratingsQuantity, price, summary, imageCover, and more.
Retrieves a monthly breakdown/statistics of tours for a given year. For each month that has tours starting in that year, the response includes the number of tours, the tour names, and the month itself — useful for planning and analytics purposes.
\n\n\nNote: The
\nyearpath variable is currently hardcoded to2021in the URL.
This request requires a Bearer Token for authentication. The token is sourced from the {{jwt}} environment variable.
Make sure the jwt variable is set in your active environment (e.g. by first sending a Login or Sign Up request, which typically sets this variable automatically via a test script).
GET {{URL}}api/v1/tours/monthly-plan/2021\nAuthorization: Bearer {{jwt}}\nA successful response returns a 200 OK status with a JSON body containing the monthly plan data:
{\n \"status\": \"success\",\n \"data\": {\n \"plan\": [\n {\n \"numTourStarts\": 3,\n \"tours\": [\"The Forest Hiker\", \"The Sea Explorer\", \"The Snow Adventurer\"],\n \"month\": 7\n },\n ...\n ]\n }\n}\nRetrieves aggregated statistical data for all tours in the Natours application. This endpoint uses a MongoDB aggregation pipeline to compute meaningful metrics grouped by tour difficulty level.
\nThis endpoint processes all tours through an aggregation pipeline that filters, groups, and sorts the data to produce a statistical summary. It is useful for gaining a high-level overview of tour offerings broken down by difficulty.
\nTypical metrics returned per difficulty group include:
\n{\n \"status\": \"success\",\n \"data\": {\n \"stats\": [\n {\n \"_id\": \"EASY\",\n \"numTours\": 4,\n \"numRatings\": 34,\n \"avgRating\": 4.675,\n \"avgPrice\": 1272,\n \"minPrice\": 397,\n \"maxPrice\": 1997\n },\n {\n \"_id\": \"MEDIUM\",\n \"numTours\": 3,\n \"numRatings\": 27,\n \"avgRating\": 4.8,\n \"avgPrice\": 1663.67,\n \"minPrice\": 497,\n \"maxPrice\": 2997\n },\n {\n \"_id\": \"DIFFICULT\",\n \"numTours\": 2,\n \"numRatings\": 25,\n \"avgRating\": 4.35,\n \"avgPrice\": 1998,\n \"minPrice\": 999,\n \"maxPrice\": 2997\n }\n ]\n }\n}\nHits an intentionally incorrect route ({{URL}}api/tours) to verify that the application's global error-handling middleware is working correctly.
The correct base path for the Natours API is /api/v1/.... By omitting the v1 segment, this request triggers a route-not-found error, which should be caught and formatted by the global error handler.
GET {{URL}}api/tours\n{\n \"status\": \"fail\",\n \"message\": \"Can't find /api/tours on this server!\"\n}\n404 response confirms the error handler is functioning as expected.Retrieves all tours that fall within a specified radius from a given geographic center point. This is a geospatial query endpoint that returns tours located within the defined distance from the provided latitude/longitude coordinates.
\nGET {{URL}}api/v1/tours/tours-within/:distance/center/:latlng/unit/:unit\nGET {{URL}}api/v1/tours/tours-within/200/center/34.111745,-118.113491/unit/mi\nThis example fetches all tours within 200 miles of the coordinates 34.111745°N, 118.113491°W (Los Angeles area).
\nmi for miles, km for kilometers.latlng value must be provided as latitude,longitude with no spaces.34.111745,-118.113491) correspond to a location in the Los Angeles, California area.URL environment variable is set to the correct base URL before sending the request.Returns the distances from a given geographical point to all available tours, expressed in miles or kilometers.
\nGET {{URL}}api/v1/tours/distances/34.111745,-118.113491/unit/mi\nlatitude,longitude pair.This request demonstrates HTTP Parameter Pollution (HPP) — a vulnerability/technique where duplicate query parameters are sent in a single request.
\nHPP occurs when an attacker (or client) sends multiple values for the same query parameter. Different web frameworks and servers handle this inconsistently:
\nThe request sends two sort parameters simultaneously:
Without HPP protection, a naive parser might receive sort=duration&sort=price and only use one of the values, or throw an error. With HPP protection (e.g. using the hpp middleware in Express), duplicate parameters are handled gracefully — typically by using the last value or by whitelisting parameters that are allowed to have multiple values.
With hpp middleware and a whitelist for sort, the API should correctly sort tours by both duration and price, returning results ordered accordingly.
You can get all tours, create new ones, and edit and delete tours. There are also special endpoints for some special requirements.
Core endpoints for managing tours in the Natours application. This folder covers the full CRUD lifecycle for tours, along with several specialized aggregation and geospatial query endpoints.
CRUD Operations
\nGet All Tours — Retrieves a list of all tours, with support for filtering, sorting, field limiting, and pagination (GET /api/v1/tours).
Get Tour — Fetches the full details of a single tour by its ID (GET /api/v1/tours/:id).
Create New Tour — Creates a new tour resource (POST /api/v1/tours).
Update Tour — Partially updates an existing tour by its ID (PATCH /api/v1/tours/:id).
Delete Tour — Permanently removes a tour by its ID (DELETE /api/v1/tours/:id).
Aggregation & Statistics
\nGet Tour Stats — Returns aggregated statistics (e.g. average rating, price, difficulty) across all tours (GET /api/v1/tours/tour-stats).
Get Monthly Plan — Returns the number of tours starting each month for a given year, useful for business planning (GET /api/v1/tours/monthly-plan/:year).
Get Top 5 Cheap Tours — A pre-aliased query that returns the five cheapest, highest-rated tours (GET /api/v1/tours/top-5-cheap).
Geospatial Queries
\nGet Tours Within Radius — Finds all tours that start within a specified distance from a given geographic coordinate (GET /api/v1/tours/tours-within/:distance/center/:latlng/unit/:unit).
Get Distances to Tours from Point — Calculates the distance from a given point to the starting location of every tour (GET /api/v1/tours/distances/:latlng/unit/:unit).
Other
\nHPP — Tests HTTP Parameter Pollution protection by sending duplicate query parameters (GET /api/v1/tours?sort=duration&sort=price).
Error Testing — Hits an intentionally incorrect route to verify global error handling behaviour (GET /api/tours).
Multiple Objects Optional — Tests optional URL parameter handling (GET /api/v1/tours/:id/:id2).
Retrieves a single review by its unique ID. This endpoint returns the full details of a specific review resource.
\nGET {{URL}}api/v1/reviews/:reviewId\nThis request uses the jwt environment variable as a Bearer token for authorization:
Authorization: Bearer {{jwt}}\nStatus: 200 OK
{\n \"status\": \"success\",\n \"data\": {\n \"review\": {\n \"_id\": \"6891a5d069cebe4c42572016\",\n \"review\": \"Review text content\",\n \"rating\": 5,\n \"createdAt\": \"2024-01-01T00:00:00.000Z\",\n \"tour\": { ... },\n \"user\": { ... }\n }\n }\n}\nError Responses:
\n","urlObject":{"path":["v1","reviews","6891a5d069cebe4c42572016"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"810df9fd-1c62-43ca-aef5-2eef6a129986"},{"name":"Get All Reviews","id":"8f18fe05-4612-469f-ad64-a4e6886ea7d5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/reviews","description":"Retrieves a list of all reviews submitted across all tours in the Natours application.
\nThis endpoint requires a valid JWT Bearer token passed via the {{jwt}} environment variable.
This endpoint supports the standard Natours API query options:
\nNone required.
\n200 OK — Returns an array of all review documents.
{\n \"status\": \"success\",\n \"results\": 10,\n \"data\": {\n \"data\": [\n {\n \"_id\": \"6891a5d069cebe4c42572016\",\n \"review\": \"Amazing experience!\",\n \"rating\": 5,\n \"createdAt\": \"2024-01-01T00:00:00.000Z\",\n \"tour\": { ... },\n \"user\": { ... }\n }\n ]\n }\n}\nGET /api/v1/tours/:tourId/reviews.Creates a new review for a specific tour. The review is associated with both a tour and a user, and includes a text review along with a numeric rating.
\nThis endpoint requires a valid JWT Bearer token. Include the token in the Authorization header using the {{jwt}} variable:
Authorization: Bearer {{jwt}}\nThe request body must be sent as raw JSON with the following fields:
\nExample:
\n{\n \"review\": \"Loved it\",\n \"rating\": 4,\n \"tour\": \"5c88fa8cf4afda39709c2951\",\n \"user\": \"6891057256313983f4c6f39f\"\n}\n201 Created — Returns the newly created review object.
{\n \"status\": \"success\",\n \"data\": {\n \"review\": {\n \"_id\": \"<new_review_id>\",\n \"review\": \"Loved it\",\n \"rating\": 4,\n \"tour\": \"5c88fa8cf4afda39709c2951\",\n \"user\": \"6891057256313983f4c6f39f\",\n \"createdAt\": \"<timestamp>\"\n }\n }\n}\nUpdates an existing review by its ID. Only the fields provided in the request body will be updated (partial update).
\nAuthentication: Requires a valid JWT token passed via the jwt variable (Bearer token).
Path Parameters:
\nid (string) — The unique identifier of the review to update. Currently hardcoded in the URL as 6892688e061d403aab98babf.Request Body (application/json):
\n{\n \"rating\": 5\n}\nAny review field can be updated (e.g. rating, review). Only the fields included in the body will be changed.
Response: Returns the updated review document.
\nBase URL: Uses the {{URL}} environment variable (currently pointing to the Prod: Natours environment).
Deletes a specific review from the database by its unique ID. This is a permanent, irreversible operation — the review will be removed entirely.
\nThis request requires a valid JWT Bearer token. The token is supplied via the jwt variable (set in the active environment or collection-level auth).
The token is sent as a Bearer token in the Authorization header:
Authorization: Bearer {{jwt}}\nMake sure the jwt variable is set in your active environment before sending this request.
\n\nNote: The review ID
\n68926406fe208a94560e1357is hardcoded in the URL. To delete a different review, update this segment with the desired review's ID.
None — this request does not require a body or any query parameters.
\n204 No Content response with an empty body is the standard REST convention for a successful delete operation.URL environment variable is set to the correct base URL (e.g., https://your-api-domain.com/) before sending.jwt token belongs to a user with the appropriate role/permissions.Endpoints for managing tour reviews in the Natours application. This folder covers the full CRUD lifecycle for reviews, which are written by users about tours they have taken.
\nGET /api/v1/reviews).GET /api/v1/reviews/:id).POST /api/v1/reviews).PATCH /api/v1/reviews/:id).DELETE /api/v1/reviews/:id).\n\n","_postman_id":"fd4f61d7-02aa-4c7c-a33e-81df901cca09"},{"name":"Tours/Reviews","item":[{"name":"Create New Review on Tour","id":"85480f86-4e76-41c6-a436-58769a4932c8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"rating\":5,\r\n \"review\":\"Amazing\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/tours/68924bc55ad67b512b95ec3c/reviews","description":"Note: Creating and updating reviews requires authentication. Include a valid JWT in the
\nAuthorizationheader asBearer {{jwt}}. For reviews scoped to a specific tour, see the Tours/Reviews folder.
Creates a new review for a specific tour. This endpoint allows authenticated users to submit a rating and written review for a tour they have taken.
\nPOST {{URL}}api/v1/tours/:tourId/reviews\nExample URL:
\nPOST {{URL}}api/v1/tours/68924bc55ad67b512b95ec3c/reviews\nThis endpoint requires authentication. A valid JWT token must be provided in the request headers.
\nThe {{jwt}} variable should be set in your active environment after logging in.
Send a JSON object with the following fields:
\nExample:
\n{\n \"rating\": 5,\n \"review\": \"Amazing\"\n}\nOn success, the API returns a 201 Created status with the newly created review object.
{\n \"status\": \"success\",\n \"data\": {\n \"review\": {\n \"_id\": \"<review_id>\",\n \"review\": \"Amazing\",\n \"rating\": 5,\n \"tour\": \"68924bc55ad67b512b95ec3c\",\n \"user\": \"<user_id>\",\n \"createdAt\": \"<timestamp>\"\n }\n }\n}\nRetrieves all reviews associated with a specific tour. This endpoint returns a list of review documents that belong to the tour identified by the tour ID in the URL.
\nGET
{{URL}}api/v1/tours/:tourId/reviews\nThe :tourId segment is a path parameter identifying the tour whose reviews you want to retrieve. In this request, it is hardcoded as 5c88fa8cf4afda39709c2951.
This endpoint may be accessed without authentication for public tour reviews. If the API enforces access control, include a valid JWT token in the Authorization header as a Bearer token:
Authorization: Bearer {{jwt}}\n/tours/:tourId/reviews), scoping reviews to a particular tour resource.This folder contains endpoints for managing reviews as a nested sub-resource of tours. Reviews in the Natours API are scoped to a specific tour, meaning all operations are performed through a nested route under the parent tour resource.
\n/api/v1/tours/:tourId/reviews\nThe :tourId path parameter identifies the tour for which reviews are being retrieved or created.
tourId in the URL path.POST endpoint requires authentication — include a valid JWT in the Authorization header as Bearer {{jwt}}.Retrieves a list of all registered users in the Natours application. This is an admin-only operation — only users with the admin role are authorised to access this endpoint.
Requires a valid JWT Bearer token passed via the {{jwt}} environment variable. The authenticated user must have the admin role.
\n\nSet the
\njwtvariable in your active environment to an admin token before sending this request.
This endpoint supports the standard Natours API query options:
\nNone required.
\n200 OK — Returns an array of all user documents.
{\n \"status\": \"success\",\n \"results\": 10,\n \"data\": {\n \"data\": [\n {\n \"_id\": \"64a1f2c3e4b0a12345678901\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"role\": \"user\",\n \"active\": true\n }\n ]\n }\n}\n403 Forbidden response.GET /api/v1/users/:id).Fetches the details of a single user by their MongoDB ObjectId. This is an admin-only operation and is part of the user management interface in the Natours API.
\nThis request requires a valid JWT Bearer token passed via the {{jwt}} environment variable. The authenticated user must have the admin role.
\n\nSet the
\njwtvariable in your active environment before sending this request.
No request body is required for this endpoint.
\n200 OKReturns the user object matching the provided id.
{\n \"status\": \"success\",\n \"data\": {\n \"data\": {\n \"_id\": \"64a1f2c3e4b0a12345678901\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"role\": \"user\",\n \"active\": true\n }\n }\n}\nadmin role.403 Forbidden if the authenticated user does not have the admin role.404 Not Found if no user exists with the given id.id must be a valid MongoDB ObjectId; an invalid format may return a 400 Bad Request or 500 error.Updates the details of any specific user by their ID. This is an admin-only operation — it allows an administrator to modify any user's data in the system.
\nThis endpoint requires a valid JWT Bearer token with admin privileges.
\n{{jwt}} environment variable.Bearer token in the Authorization header.403 Forbidden error.\n\nMake sure the
\njwtvariable is set to an admin token in your active environment before sending this request.
Send the body as raw JSON. Only include the fields you want to update — this is a partial update (PATCH), so omitted fields remain unchanged.
Example:
\n{\n \"name\": \"Jane Doe\",\n \"email\": \"jane@example.com\",\n \"role\": \"guide\"\n}\n\n\n⚠️ Do not include
\npasswordorpasswordConfirmin this request body. Password updates are not handled here — use the dedicated Update Password endpoint instead.
Success — 200 OK
{\n \"status\": \"success\",\n \"data\": {\n \"user\": {\n \"_id\": \"68908f0d31c6fe58b8cb9a36\",\n \"name\": \"Jane Doe\",\n \"email\": \"jane@example.com\",\n \"role\": \"guide\",\n \"photo\": \"default.jpg\",\n \"active\": true\n }\n }\n}\nError Responses
\n400 or 500 error depending on the implementation.filterObj whitelist will be updated; any other fields sent in the body will be silently ignored.Permanently deletes a user account by its ID. This is an admin-only operation — only users with the admin role are authorised to call this endpoint.
Requires a valid JWT Bearer token passed via the {{jwt}} environment variable. The authenticated user must have the admin role.
DELETE {{URL}}api/v1/users/:id\nNone required.
\nOn success, the server returns a 204 No Content response with no response body, indicating the user has been permanently removed.
DELETE /api/v1/users/deleteMe), which sets the account to inactive rather than removing it.403 Forbidden response.Retrieves the profile data of the currently authenticated user.
\nThis endpoint requires a valid JWT token. The token should be passed as a Bearer token in the Authorization header, or via a cookie depending on the server configuration.
\n\nThe
\n{{jwt}}variable is used to supply the authentication token.
No request body is required for this endpoint.
\nReturns the data of the currently logged-in user, including profile information such as name, email, and role.
\n{{URL}} variable should be set to the base URL of the Natours API (e.g., https://your-api-domain.com/).401 Unauthorized response.Allows the currently authenticated user to update their own profile information. This endpoint accepts multipart form data, making it suitable for file uploads such as a new profile photo.
\n\n\n⚠️ Note: This endpoint does not update passwords. To change your password, use the dedicated change-password endpoint.
\n
Requires a valid JWT Bearer token, provided via the {{jwt}} environment variable.
Method: PATCH
URL: {{URL}}api/v1/users/updateMe
Body Type: multipart/form-data
Soft-deletes the currently authenticated user by setting their account status to inactive. The user's data is retained in the database but the account is no longer accessible.
\n\n\nNote: This action deactivates the account associated with the JWT provided in the
\nAuthorizationheader. It does not permanently remove the user record from the database.
This endpoint requires a valid JWT bearer token. Include it in the Authorization header:
Authorization: Bearer <token>\nThe jwt variable from the active environment is used automatically.
DELETE{{URL}}api/v1/users/deleteMeEndpoints for managing user accounts in the Natours application. This folder covers both admin-level user management and self-service operations for the currently authenticated user.
\nAdmin Operations
\nGET /api/v1/users).GET /api/v1/users/:id).PATCH /api/v1/users/:id).DELETE /api/v1/users/:id).Current User (Self-Service)
\nGET /api/v1/users/me).PATCH /api/v1/users/updateMe).DELETE /api/v1/users/deleteMe).Updates the password of the currently authenticated user. The user must provide their current password along with the new password and a confirmation of the new password.
\nThis endpoint requires a valid JWT token. The token is read from the {{jwt}} environment variable and must be sent as a Bearer token in the Authorization header.
The request body must be sent as raw JSON.
\nExample:
\n{\n \"passwordCurrent\": \"pass1234\",\n \"password\": \"newpassword\",\n \"passwordConfirm\": \"newpassword\"\n}\nOn success, the server returns a new JWT token (since the password change invalidates the old one). The test script automatically saves the new token to the {{jwt}} environment variable for use in subsequent requests.
Example response shape:
\n{\n \"status\": \"success\",\n \"token\": \"<new_jwt_token>\",\n \"data\": {\n \"user\": { ... }\n }\n}\npasswordCurrent field is validated server-side — an incorrect value will result in an error response.password and passwordConfirm must match; a mismatch will result in a validation error.{{jwt}} environment variable by the post-response test script.Initiates a password reset flow by sending a password reset email to the provided email address.
\nPOST {{URL}}api/v1/users/forgetPassword
Send a JSON object with the following field:
\nExample:
\n{\n \"email\": \"user@example.com\"\n}\nUpon a successful request, the server generates a password reset token and sends a reset link/token to the provided email address. The user can then use that link or token to set a new password.
\nAuthenticates an existing user and returns a JWT token for use in subsequent authenticated requests.
\nSend a JSON object with the following required fields:
\nExample:
\n{\n \"email\": \"zubair@mailsac.com\",\n \"password\": \"{{password}}\"\n}\nOn success, the response contains a JWT token:
\n{\n \"token\": \"<jwt_token>\"\n}\nThe test script automatically saves the returned token to the jwt environment variable, so it can be used in subsequent requests without manual copying:
pm.environment.set(\"jwt\", pm.response.json().token);\nRegisters a new user account in the Natours application.
\nPOST {{URL}}api/v1/users/signup\nSend a JSON object with the following fields:
\nExample:
\n{\n \"name\": \"Jonas Schmedtmann\",\n \"email\": \"admin@natours.io\",\n \"password\": \"test1234\",\n \"passwordConfirm\": \"test1234\"\n}\nOn success, the API returns a 201 Created response containing a JWT token in the token field of the response body.
\n\n","urlObject":{"path":["v1","users","signup"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"209c9bbc-2bf9-4105-b84c-b14efeaf5afb"},{"name":"Reset Password","event":[{"listen":"test","script":{"id":"e0595783-1767-4be8-b2a4-d68c4b036de4","exec":["pm.environment.set(\"jwt\", pm.response.json().token);"],"type":"text/javascript"}}],"id":"c63e09bb-ae12-47da-991c-b7679ec21264","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\r\n \"password\":\"newpassword\",\r\n \"passwordConfirm\":\"newpassword\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/resetPassword/682a10211e1a0ab6a81e91520baa60538ec73f88660cd012e06f5f9421af3d2d","description":"Note: The test script automatically saves the returned token to the
\njwtenvironment variable, making it available for authenticated requests throughout the collection.
Resets a user's password using a valid password reset token. This endpoint is typically called after the user has received a reset link via email (from the Forgot Password endpoint) and clicked through to the reset form.
\nPATCH {{URL}}api/v1/users/resetPassword/:resetToken\nExample token in URL:
\n682a10211e1a0ab6a81e91520baa60538ec73f88660cd012e06f5f9421af3d2d\nSend a raw JSON body with the following fields:
\nExample:
\n{\n \"password\": \"newpassword\",\n \"passwordConfirm\": \"newpassword\"\n}\nOn success, the server returns a JSON object containing a JWT token, which is used to authenticate subsequent requests.
\nThe test script automatically saves this token to the active environment:
\npm.environment.set(\"jwt\", pm.response.json().token);\njwt token can be used for authenticated requests.password and passwordConfirm match; a mismatch will result in a validation error.Handles all user authentication and account security flows for the Natours API.
\nPOST /api/v1/users/signup).POST /api/v1/users/login).POST /api/v1/users/forgetPassword).PATCH /api/v1/users/resetPassword/:token).PATCH /api/v1/users/updateMyPassword).Retrieves a single booking by its unique ID. Returns the full booking object associated with the specified booking ID.
\nThis endpoint requires a valid JWT bearer token. The token must be included in the request via the {{jwt}} variable, which is resolved from the active environment.
GET {{URL}}api/v1/bookings/68a5b59b90d4ebdfb03fe0bc\nNo query parameters or request body required.
\nStatus: 200 OK
Returns a booking object containing details such as the tour, user, price, and booking date.
\n{\n \"status\": \"success\",\n \"data\": {\n \"booking\": {\n \"_id\": \"68a5b59b90d4ebdfb03fe0bc\",\n \"tour\": { ... },\n \"user\": { ... },\n \"price\": 997,\n \"createdAt\": \"2024-01-01T00:00:00.000Z\",\n \"paid\": true\n }\n }\n}\nRetrieves a list of all bookings in the Natours system. This is an admin-only endpoint — only users with the admin role are authorised to access it.
GET {{URL}}api/v1/bookings\nRequires a valid JWT Bearer token passed via the {{jwt}} environment variable. The authenticated user must have the admin role.
GETOn success, the server returns a JSON object containing:
\nstatus: \"success\"results: The total number of bookings returneddata: An object with a bookings array, where each booking document includes details such as the associated tour, user, price, and creation date.403 Forbidden response.Initiates a Stripe checkout session for a specific tour booking. This endpoint generates a Stripe-hosted payment page URL that the client can redirect the user to in order to complete their booking payment.
\nGET {{URL}}api/v1/bookings/checkout-session/:tourId\nRequires a valid JWT Bearer token passed via the {{jwt}} variable. The user must be logged in to initiate a checkout session.
GETOn success, the server returns a Stripe checkout session object containing:
\nstatus: \"success\"session: A Stripe session object that includes the url property — the hosted Stripe payment page the user should be redirected to in order to complete the booking.Endpoints for managing tour bookings in the Natours application.
\nGET /api/v1/bookings/checkout-session/:tourId).GET /api/v1/bookings).GET /api/v1/bookings/:id).