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 Properties API exposes accommodation listings across Costa Rica — hotels, eco-lodges, villas, cabins, glamping, and more. Public read endpoints return paginated results with optional filters. Write operations (create, update, delete) require an authenticated vendor account. All IDs are UUIDs. Responses and cache are invalidated automatically on every write.

​
GET /api/v1/properties/

Returns a paginated list of active properties. Results are cached for 5 minutes and keyed by every combination of query parameters.
​
page
integer
default:"1"
Page number (1-indexed).
​
page_size
integer
default:"20"
Items per page. Maximum 100.
​
region
string
Filter by region name (exact match). Use GET /api/v1/properties/regions to get a distinct list of available regions.
​
property_type
string
Filter by accommodation type. Accepted values: hotel, hostel, eco_lodge, resort, villa, apartment, cabin, glamping, boutique, aparthotel.
​
category
string
Filter by location category. Accepted values: beach, mountain, jungle, city, rural, lake.
​
min_price
number
Minimum base_price (USD).
​
max_price
number
Maximum base_price (USD).
​
rating
number
Minimum average rating (0–5).
​
featured
boolean
When true, returns only featured listings.
Response 200 
{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Beachfront Eco-Lodge",
      "slug": "beachfront-eco-lodge-a1b2c3d4",
      "short_description": "Secluded eco-lodge steps from the Pacific.",
      "property_type": "eco_lodge",
      "category": "beach",
      "city": "Uvita",
      "region": "Puntarenas",
      "province": "Puntarenas",
      "cover_image": "https://res.cloudinary.com/maleku/image/upload/v1/properties/cover.jpg",
      "rating": 4.8,
      "total_reviews": 42,
      "base_price": 185.00,
      "is_active": true
    }
  ],
  "total": 128,
  "page": 1,
  "page_size": 20,
  "total_pages": 7,
  "has_next": true,
  "has_prev": false
}

​
POST /api/v1/properties/

Creates a new property listing. Requires VENDOR or SUPER_ADMIN role. The vendor’s profile must exist before calling this endpoint. A URL-friendly slug is generated automatically from the property name with a UUID suffix. Auth: Bearer token — Vendor or SUPER_ADMIN Rate limit: 10 requests/minute per IP Request body 
{
  "name": "Mountain Cabin Monteverde",
  "short_description": "Cozy cabin with cloud-forest views.",
  "description": "Nestled in the cloud forest of Monteverde...",
  "property_type": "cabin",
  "category": "mountain",
  "address": "Santa Elena, Monteverde",
  "country": "Costa Rica",
  "province": "Puntarenas",
  "region": "Monteverde",
  "city": "Santa Elena",
  "latitude": 10.3119,
  "longitude": -84.8269,
  "amenities": ["wifi", "kitchen", "hot_water", "parking"],
  "features": ["forest_view", "private_porch"],
  "check_in_time": "15:00",
  "check_out_time": "11:00",
  "cancellation_policy": "Free cancellation up to 48 hours before check-in.",
  "min_guests": 1,
  "max_guests": 4,
  "beds": 2,
  "baths": 1,
  "base_price": 120.00,
  "currency": "USD",
  "weekend_price": 145.00,
  "weekly_discount": 10
}
Response 201 
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "vendor_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Mountain Cabin Monteverde",
  "slug": "mountain-cabin-monteverde-b2c3d4e5",
  "property_type": "cabin",
  "category": "mountain",
  "base_price": 120.00,
  "weekend_price": 145.00,
  "weekly_discount": 10.0,
  "currency": "USD",
  "rating": 0.0,
  "total_reviews": 0,
  "is_active": true,
  "is_featured": false,
  "rooms": [],
  "created_at": "2025-01-15T14:32:00Z"
}

​
GET /api/v1/properties/regions

Returns a deduplicated list of all regions where active properties are located. Useful for populating filter dropdowns. Auth: Public Response 200 
{ "regions": ["Guanacaste", "Puntarenas", "Monteverde", "La Fortuna", "Caribbean"] }

​
GET /api/v1/properties/vendor/my

Returns the authenticated vendor’s own property listings with pagination. Only accounts with the VENDOR role may call this endpoint. Auth: Bearer token — Vendor role required Query parameters: page, page_size (same pagination params as the public list endpoint) Response 200 — same PaginatedResponse shape as the public list endpoint, scoped to the vendor’s own properties.

​
GET /api/v1/properties/slug/

Returns a single property by its URL-friendly slug. Response is cached for 10 minutes. Auth: Public Response 200 — same PropertyResponse as the UUID lookup Response 404 — { "detail": "Property not found" }

​
GET /api/v1/properties/

Returns a single property by UUID with all related rooms, vendor public info, and reviews. Response is cached for 10 minutes. Response 200 — Full PropertyResponse with:
  • rooms[] — list of RoomSchema objects, each containing price_per_night, weekend_price, extra_guest_price, cleaning_fee, max_guests, bed_type, images
  • vendor — public vendor summary (name, rating, total_reviews)
  • All fields from the property model
Response 404 — { "detail": "Property not found" }

​
PUT /api/v1/properties/

Updates an existing property. Only the owning vendor or a SUPER_ADMIN may update. All fields are optional; only supplied fields are changed (partial update). Mass-assignment is prevented — only the fields in the ALLOWED_FIELDS list are accepted. Auth: Bearer token — Owner Vendor or SUPER_ADMIN Rate limit: 10 requests/minute per IP Request body — any subset of PropertyUpdate fields, for example: 
{
  "base_price": 135.00,
  "weekend_price": 160.00,
  "amenities": ["wifi", "kitchen", "hot_water", "parking", "fireplace"],
  "is_featured": true
}
Response 200 — updated PropertyResponse

​
DELETE /api/v1/properties/

Soft-deletes the property by setting is_active = false. The record is not removed from the database. Auth: Bearer token — Owner Vendor or SUPER_ADMIN Response 200 
{ "message": "Property deleted successfully" }
Maleku uses a soft-delete strategy. When a property is deleted, is_active is set to false and the record remains in the database. A deleted_at timestamp field is also present on the model for full audit support. Deleted properties are excluded from all public listing queries automatically.

​
POST /api/v1/properties//images

Uploads an image file to a property. The file is stored in Cloudinary if configured, falling back to local storage. When is_cover is true, the uploaded URL also becomes the property’s cover_image. Auth: Bearer token — Owner Vendor or SUPER_ADMIN Rate limit: 10 requests/minute per IP Content-Type: multipart/form-data
FieldTypeDescription
filebinaryImage file (jpg, jpeg, png, gif, webp). Max 10 MB.
is_coverbooleanWhen true, sets this image as the cover. Defaults to false.
Response 200 — updated PropertyResponse with new image appended to images[] and cover_image set if applicable.

​
PUT /api/v1/properties//cover

Sets or replaces the cover image URL for a property using an existing URL string (not a file upload). If the URL is not already in images[], it is appended. Auth: Bearer token — Owner Vendor or SUPER_ADMIN Rate limit: 10 requests/minute per IP Query parameter: image_url — the URL to set as cover image. Response 200 — updated PropertyResponse

​
DELETE /api/v1/properties//images

Removes an image URL from the property’s images[] array. If the removed URL matches cover_image, the cover is also cleared. Auth: Bearer token — Owner Vendor or SUPER_ADMIN Query parameter: image_url — the URL to remove. Response 200 — updated PropertyResponse

​
Key Model Fields

The table below describes the most important fields of the Property model stored in PostgreSQL.
FieldTypeDescription
idUUIDPrimary key
vendor_idUUIDFK to vendors
namestring(255)Display name
slugstring(255)URL-friendly unique identifier
property_typeenumhotel, hostel, eco_lodge, resort, villa, apartment, cabin, glamping, boutique, aparthotel
categoryenumbeach, mountain, jungle, city, rural, lake
addressstring(500)Street address
latitude / longitudefloatGeographic coordinates
base_pricenumeric(10,2)Weekday nightly rate (USD)
weekend_pricenumeric(10,2)Friday/Saturday nightly rate (USD)
weekly_discountnumeric(5,2)Percentage discount for stays ≥ 7 nights
amenitiesJSONB arraye.g. ["wifi", "pool", "kitchen"]
featuresJSONB arraye.g. ["ocean_view", "private_pool"]
cover_imagestring(500)Primary image URL
imagesJSON arrayAll image URLs
check_in_timestringDefault "15:00"
check_out_timestringDefault "11:00"
is_activebooleanControls public visibility
is_featuredbooleanHighlighted in featured sections
ratingfloatComputed average (0–5)
deleted_attimestampSet on soft delete

​
Room fields (nested in PropertyResponse)

Each room under a property has its own pricing:
FieldTypeDescription
price_per_nightnumericBase nightly rate
weekend_pricenumericWeekend nightly rate
extra_guest_pricenumericPer-person surcharge above base occupancy
cleaning_feenumericOne-time cleaning charge
max_guestsintegerMaximum occupancy
bed_typestringe.g. "King", "Twin"
is_availablebooleanAvailability status

Build docs developers (and LLMs) love

Get started for freeTalk to us