Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt

Use this file to discover all available pages before exploring further.

The Reviews API allows guests to leave star ratings and text feedback on the properties and tours they have booked. Reviews are tied to a specific booking — not just a resource — which means every review is verified against a real stay or tour participation. Approved reviews feed directly into the vendor’s aggregate rating and total_reviews score, which influences listing ranking across the platform.
Only users who have a booking with status = "completed" for the target property or tour can submit a review. Attempting to review an incomplete or non-existent booking returns 400 Bad Request. Each booking can only be reviewed once — duplicate review attempts return 409 Conflict.

​
POST /api/v1/reviews

Creates a new review. The review is automatically linked to the property or tour associated with the booking. On success, the owning vendor’s rating and total_reviews are recalculated immediately using an aggregated query across all approved reviews for that vendor’s listings. Auth: Bearer token
​
booking_id
string
required
UUID of the completed booking being reviewed.
​
rating
integer
required
Star rating from 1 to 5 (inclusive).
​
title
string
Optional short headline for the review (e.g. "Amazing experience!").
​
comment
string
Optional full review text.
Request body 
{
  "booking_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "rating": 5,
  "title": "Incredible eco-lodge — will be back!",
  "comment": "The staff were phenomenal and the ocean views from the cabins are unbeatable. Very sustainable practices throughout."
}
Response 201 
{
  "id": "f7a8b9c0-d1e2-3456-1234-567890abcdef",
  "rating": 5,
  "title": "Incredible eco-lodge — will be back!",
  "comment": "The staff were phenomenal and the ocean views from the cabins are unbeatable. Very sustainable practices throughout.",
  "user_name": "Ana Rodríguez",
  "created_at": "2025-07-01T10:22:45Z"
}
Error responses
StatusCause
404Booking not found or does not belong to the authenticated user
400Booking status is not completed
400Booking has no associated property or tour
409A review already exists for this booking

​
List Reviews

Reviews are not exposed through a dedicated list route in the Reviews router. They are returned as part of the PropertyResponse and TourResponse objects when fetching a specific listing via GET /api/v1/properties/{id} or GET /api/v1/tours/{id}.

​
Key Fields

​
id
UUID
Unique review identifier.
​
rating
integer
Star rating between 1 (worst) and 5 (best). Validated with ge=1, le=5.
​
title
string | null
Optional short headline for the review.
​
comment
string | null
Optional free-text review body.
​
user_name
string | null
Full name of the reviewer, derived from current_user.full_name at review creation time.
​
created_at
datetime
Timestamp when the review was submitted.
The Review model also stores:
FieldDescription
booking_idFK to the booking that backs this review
property_idFK to the reviewed property (if a property booking)
tour_idFK to the reviewed tour (if a tour booking)
user_idFK to the reviewer
is_approvedAuto-set to true on creation; can be moderated by admins
deleted_atSoft-delete timestamp

​
Effect on Vendor Ratings

When a review is created or deleted, the system recalculates the vendor’s aggregate score in a single SQL aggregation: 
SELECT AVG(rating), COUNT(id)
FROM reviews
WHERE is_approved = true
  AND deleted_at IS NULL
  AND (property_id IN (vendor's property IDs)
       OR tour_id IN (vendor's tour IDs))
The result is written back to Vendor.rating (rounded to 1 decimal place) and Vendor.total_reviews. This keeps vendor scores consistent with only approved, non-deleted reviews and means new reviews are reflected in vendor listings immediately.

Build docs developers (and LLMs) love

Get started for freeTalk to us