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.

Vendors are the marketplace sellers on Maleku System — tour operators, property managers, vehicle rental companies, boat charter providers, and transportation services. Each vendor has a public profile page (/slug/{slug}/landing) that aggregates all their active listings, reviews, and statistics. Vendor list responses are cached at the API layer to reduce database load.
Unverified vendors’ listings are not shown publicly. A vendor must be verified by a Super Admin before their properties, tours, and other listings appear in search results and on the public marketplace.

​
GET /api/v1/vendors/

List active vendors sorted by rating in descending order. Returns a flat array of public vendor summaries. Response is cached for 300 seconds.
​
limit
integer
default:"20"
Number of vendors to return. Range: 1–100.
​
offset
integer
default:"0"
Number of vendors to skip (for manual pagination).
Response — VendorPublicResponse[] 
[
  {
    "id": "a1b2c3d4-...",
    "business_name": "Tropical Adventures CR",
    "business_type": "tour_operator",
    "description": "Premier adventure tours across Costa Rica since 2010.",
    "logo_url": "https://cdn.maleku.dev/vendors/tropical-logo.jpg",
    "rating": 4.9,
    "total_reviews": 312
  },
  {
    "id": "e5f6a7b8-...",
    "business_name": "Pacific Coast Hotels",
    "business_type": "property_manager",
    "description": "Luxury beachfront properties along the Pacific coast.",
    "logo_url": "https://cdn.maleku.dev/vendors/pacific-logo.jpg",
    "rating": 4.7,
    "total_reviews": 185
  }
]
Vendor lists are cached for 300 seconds and vendor detail pages are cached for 600 seconds. To force fresh data after updating a vendor record, call PUT /api/v1/vendors/me/profile — this triggers VendorService.invalidate_cache() and clears both the list and detail cache keys automatically.

​
GET /api/v1/vendors/

Get full vendor details by UUID. Response is cached for 600 seconds. Includes business name, rating, verification status, review count, and commission rate. Response — VendorResponse 
{
  "id": "a1b2c3d4-...",
  "user_id": "f9e8d7c6-...",
  "business_name": "Tropical Adventures CR",
  "business_type": "tour_operator",
  "description": "Premier adventure tours across Costa Rica since 2010.",
  "phone": "+50622334455",
  "email": "info@tropicaladventures.cr",
  "rating": 4.9,
  "total_reviews": 312,
  "is_verified": true,
  "is_active": true,
  "created_at": "2023-06-01T09:00:00Z"
}

​
GET /api/v1/vendors/slug/

Get full vendor details by the vendor’s URL-friendly business_slug. Behaves identically to the UUID endpoint — response cached for 600 seconds. 
curl "https://api.maleku.dev/api/v1/vendors/slug/tropical-adventures-cr"

​
GET /api/v1/vendors/slug//landing

Get all data needed to render the public vendor landing page in a single request. Includes the top 5 listings per category (properties, tours, vehicles, boats, transportation), reviews, booking stats, and marketplace ranking. Supports optional authentication: if a valid Bearer token is provided, the can_review flag is set to true when the authenticated user has completed bookings with this vendor that have not yet been reviewed. Response — VendorLandingResponse 
{
  "id": "a1b2c3d4-...",
  "business_name": "Tropical Adventures CR",
  "business_slug": "tropical-adventures-cr",
  "business_type": "tour_operator",
  "description": "Premier adventure tours across Costa Rica since 2010.",
  "logo_url": "https://cdn.maleku.dev/vendors/tropical-logo.jpg",
  "cover_image": "https://cdn.maleku.dev/vendors/tropical-cover.jpg",
  "phone": "+50622334455",
  "email": "info@tropicaladventures.cr",
  "address": "La Fortuna, Alajuela",
  "rating": 4.9,
  "total_reviews": 312,
  "is_verified": true,
  "properties": [...],
  "properties_has_more": false,
  "tours": [...],
  "tours_has_more": true,
  "vehicles": [],
  "vehicles_has_more": false,
  "boats": [],
  "boats_has_more": false,
  "transportation": [...],
  "transportation_has_more": false,
  "reviews": [...],
  "reviews_total": 312,
  "reviews_average_rating": 4.9,
  "stats": {
    "total_properties": 3,
    "total_tours": 14,
    "total_vehicles": 0,
    "total_boats": 0,
    "total_transportation": 2,
    "total_reviews": 312,
    "total_bookings": 1450,
    "member_since": "2023-06-01T09:00:00Z"
  },
  "ranking": {
    "position": 2,
    "total_vendors": 48
  },
  "can_review": false,
  "eligible_booking_ids": []
}

​
GET /api/v1/vendors/me/profile

Get the authenticated vendor’s own profile. Requires vendor role. Returns the full VendorResponse for the vendor account linked to the current user.

​
PUT /api/v1/vendors/me/profile

Update the authenticated vendor’s own profile. Requires vendor role. Rate-limited to 10 requests per minute. Only the following fields can be updated by the vendor themselves (mass assignment protection):
​
business_name
string
Public business name.
​
description
string
Business description shown on the vendor profile page.
​
phone
string
Contact phone number.
​
address
string
Physical business address.
​
city
string
City.
​
country
string
Country (defaults to Costa Rica).
​
website
string
Business website URL.
​
logo_url
string
URL for the business logo image.
​
tax_id
string
Tax identification number for compliance.

​
GET /api/v1/vendors/me/analytics

Get the authenticated vendor’s analytics dashboard. Requires vendor role. Returns booking counts by status, total revenue from completed bookings, and commission rate. Response 
{
  "total_properties": 3,
  "total_tours": 14,
  "total_bookings": 1450,
  "pending_bookings": 12,
  "confirmed_bookings": 38,
  "completed_bookings": 1380,
  "total_revenue": 287450.00,
  "rating": 4.9,
  "total_reviews": 312,
  "commission_rate": 0.10
}

​
PUT /api/v1/vendors//verify

Mark a vendor as verified. Requires super_admin role. Sets is_verified = true on the vendor record and invalidates the vendor cache. Rate-limited to 10 requests per minute. 
curl -X PUT "https://api.maleku.dev/api/v1/vendors/{vendor_id}/verify" \
  -H "Authorization: Bearer <superadmin_token>"
Response 
{ "message": "Vendor verified successfully" }

​
PUT /api/v1/vendors//activate

Toggle a vendor’s active status. Requires super_admin role. Pass is_active=true or is_active=false as a query parameter. 
# Deactivate a vendor
curl -X PUT "https://api.maleku.dev/api/v1/vendors/{vendor_id}/activate?is_active=false" \
  -H "Authorization: Bearer <superadmin_token>"

​
VendorPublicResponse Schema

​
id
UUID
Vendor’s unique identifier.
​
business_name
string
Public-facing business name.
​
business_type
string
Category of business (e.g. tour_operator, property_manager, vehicle_rental).
​
description
string | null
Short business description.
​
logo_url
string | null
URL for the vendor’s logo image.
​
rating
float | null
Average rating across all listings (0–5).
​
total_reviews
integer | null
Total number of approved reviews across all listings.

Build docs developers (and LLMs) love

Get started for freeTalk to us