Vehicles and Boats API — Transportation Listings

Maleku System offers two distinct transportation listing APIs: Vehicles for car and ground-transport rentals, and Boats for nautical equipment including boats, jet skis, and kayaks. Both follow the same CRUD pattern. Write operations require an authenticated vendor. Soft deletes are used — is_active is set to false rather than removing the record.

Vehicles

The Vehicles API manages rentable ground-transport listings — cars, SUVs, vans, minibuses, and motorcycles.

GET /api/v1/vehicles/

Returns a paginated list of active, available vehicles. Results are ordered by price_per_day ascending. Auth: Bearer token (authenticated users only)

location

string

Filter by pickup location (partial ILIKE match).

vehicle_type

string

Filter by vehicle type. Accepted values: car, suv, van, minibus, motorcycle.

seats

integer

Minimum seating capacity required.

skip

integer

default:"0"

Number of records to skip (offset-based pagination).

limit

integer

default:"20"

Maximum records to return. Capped at 100.

Response 200

{
  "items": [
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "vendor_id": "f6a7b8c9-d0e1-2345-f012-345678901bcd",
      "vehicle_type": "suv",
      "brand": "Toyota",
      "model": "RAV4",
      "year": 2023,
      "transmission": "automatic",
      "fuel_type": "gasoline",
      "seats": 5,
      "color": "White",
      "price_per_day": 75.00,
      "price_per_week": 490.00,
      "price_per_month": 1800.00,
      "deposit_amount": 300.00,
      "location": "San José, SJO Airport",
      "pickup_locations": ["SJO Airport", "Downtown San José"],
      "requirements": ["Valid driver's license", "Credit card for deposit"],
      "is_available": true,
      "is_active": true,
      "rating": 4.6,
      "total_reviews": 18
    }
  ],
  "total": 34,
  "skip": 0,
  "limit": 20
}

POST /api/v1/vehicles/

Creates a new vehicle listing. Only vendors with an existing vendor profile may create listings. Auth: Bearer token — Vendor role required Rate limit: 10 requests/minute per IP Request body

{
  "vehicle_type": "suv",
  "brand": "Toyota",
  "model": "RAV4",
  "year": 2023,
  "transmission": "automatic",
  "fuel_type": "gasoline",
  "seats": 5,
  "license_plate": "CRC-1234",
  "color": "White",
  "features": {
    "air_conditioning": true,
    "gps": true,
    "bluetooth": true,
    "child_seat": false
  },
  "price_per_day": 75.00,
  "price_per_week": 490.00,
  "price_per_month": 1800.00,
  "deposit_amount": 300.00,
  "location": "San José, SJO Airport",
  "pickup_locations": ["SJO Airport", "Downtown San José"],
  "dropoff_locations": ["SJO Airport", "LIR Airport"],
  "requirements": ["Valid driver's license", "Credit card for deposit"],
  "insurance_options": { "basic": 8.00, "full": 18.00 }
}

Response 201 — full vehicle object including generated id, vendor_id, created_at, and updated_at.

GET /api/v1/vehicles/

Returns detailed information for a specific vehicle by UUID. Auth: Public Response 404 — { "detail": "Vehicle not found" }

PUT /api/v1/vehicles/

Updates a vehicle. Only the owning vendor may update. The vendor profile is verified by matching vendor_id against the authenticated user. Auth: Bearer token — Owner Vendor Rate limit: 10 requests/minute per IP Request body — any subset of VehicleUpdate fields, for example:

{
  "price_per_day": 80.00,
  "is_available": false
}

DELETE /api/v1/vehicles/

Soft-deletes the vehicle by setting is_active = false. Auth: Bearer token — Owner Vendor Response 200

{ "message": "Vehicle deleted" }

Key Vehicle Fields

Field	Type	Description
`vehicle_type`	enum	`car`, `suv`, `van`, `minibus`, `motorcycle`
`brand`	string(50)	Manufacturer, e.g. `"Toyota"`
`model`	string(100)	Model name, e.g. `"RAV4"`
`year`	integer	Model year (2000–2030)
`transmission`	enum	`automatic`, `manual`
`fuel_type`	enum	`gasoline`, `diesel`, `electric`, `hybrid`
`seats`	integer	Seating capacity (1–50)
`price_per_day`	float	Daily rental rate (USD)
`price_per_week`	float	Weekly rental rate (USD)
`price_per_month`	float	Monthly rental rate (USD)
`deposit_amount`	float	Security deposit amount (USD)
`location`	string	Primary pickup location
`pickup_locations`	string[]	Available pickup points
`dropoff_locations`	string[]	Available drop-off points
`features`	object	Key/value map of vehicle features
`insurance_options`	object	Available insurance tiers and their daily rates (USD)
`requirements`	string[]	Renter requirements
`is_available`	boolean	Real-time availability flag

GET /api/v1/vehicles/vendor/my-vehicles

Returns the authenticated vendor’s own vehicle listings. Auth: Bearer token — Vendor role required Response 200 — array of VehicleResponse objects belonging to the vendor.

Boats

The Boats API manages nautical rental listings — motor boats, jet skis, kayaks, paddleboards, and dive equipment.

GET /api/v1/boats/

Returns a paginated list of active, available nautical equipment. Results are ordered by price_per_day ascending. Auth: Bearer token (authenticated users only)

location

string

Filter by operating location (partial ILIKE match).

equipment_type

string

Filter by equipment type. Accepted values: boat, jet_ski, kayak, paddleboard, equipment.

capacity

integer

Minimum passenger capacity required.

skip

integer

default:"0"

Offset for pagination.

limit

integer

default:"20"

Maximum records to return. Capped at 100.

Response 200

{
  "items": [
    {
      "id": "a7b8c9d0-e1f2-3456-0123-456789abcdef",
      "vendor_id": "b8c9d0e1-f2a3-4567-1234-567890bcdef0",
      "equipment_type": "boat",
      "brand": "Yamaha",
      "model": "242X",
      "year": 2022,
      "capacity": 8,
      "length_foot": 24.0,
      "price_per_hour": 120.00,
      "price_per_day": 650.00,
      "price_per_week": 3800.00,
      "location": "Quepos, Marina Pez Vela",
      "operating_area": "Pacific coast, Manuel Antonio",
      "requires_license": false,
      "is_available": true,
      "is_active": true,
      "rating": 4.9,
      "total_reviews": 11
    }
  ],
  "total": 19,
  "skip": 0,
  "limit": 20
}

POST /api/v1/boats/

Creates a new nautical equipment listing. Auth: Bearer token — Vendor role required Rate limit: 10 requests/minute per IP Request body

{
  "equipment_type": "boat",
  "brand": "Yamaha",
  "model": "242X",
  "year": 2022,
  "capacity": 8,
  "length_foot": 24.0,
  "features": {
    "life_jackets": true,
    "cooler": true,
    "fishing_gear": false,
    "snorkeling_gear": true
  },
  "price_per_hour": 120.00,
  "price_per_day": 650.00,
  "price_per_week": 3800.00,
  "location": "Quepos, Marina Pez Vela",
  "operating_area": "Pacific coast, Manuel Antonio",
  "requires_license": false,
  "license_notes": "Captain provided — no guest license required."
}

Response 201 — full boat equipment object.

GET /api/v1/boats/

Returns detailed information for a specific piece of nautical equipment. Auth: Public Response 404 — { "detail": "Boat equipment not found" }

PUT /api/v1/boats/

Updates a boat listing. Only the owning vendor may update. Auth: Bearer token — Owner Vendor Rate limit: 10 requests/minute per IP

DELETE /api/v1/boats/

Soft-deletes the boat by setting is_active = false. Auth: Bearer token — Owner Vendor Response 200

{ "message": "Boat equipment deleted" }

Key Boat Fields

Field	Type	Description
`equipment_type`	enum	`boat`, `jet_ski`, `kayak`, `paddleboard`, `equipment`
`brand`	string(50)	Manufacturer name
`model`	string(100)	Model name
`year`	integer	Manufacture year (2000–2030)
`capacity`	integer	Passenger capacity (1–100)
`length_foot`	float	Vessel length in feet
`price_per_hour`	float	Hourly charter rate (USD)
`price_per_day`	float	Daily charter rate (USD)
`price_per_week`	float	Weekly charter rate (USD)
`location`	string	Marina or base location
`operating_area`	string	Geographic area of operation
`requires_license`	boolean	Whether a captain’s license is needed
`license_notes`	string	Notes about license requirements
`features`	object	Key/value map of onboard features
`is_available`	boolean	Real-time availability flag

GET /api/v1/boats/vendor/my-boats

Returns the authenticated vendor’s own nautical equipment listings. Auth: Bearer token — Vendor role required Response 200 — array of BoatEquipmentResponse objects belonging to the vendor.

Transportation

Maleku System includes a dedicated Transportation API for airport shuttles and private transfer services. That API lives at /api/v1/transportation/ and is documented separately. It is not part of the Vehicles or Boats APIs.

Overview

Listings

Transactions

Discovery

Platform Management

Vehicles and Boats API — Transportation Listings

Vehicles

GET /api/v1/vehicles/

POST /api/v1/vehicles/

GET /api/v1/vehicles/

PUT /api/v1/vehicles/

DELETE /api/v1/vehicles/

Key Vehicle Fields

GET /api/v1/vehicles/vendor/my-vehicles

Boats

GET /api/v1/boats/

POST /api/v1/boats/

GET /api/v1/boats/

PUT /api/v1/boats/

DELETE /api/v1/boats/

Key Boat Fields

GET /api/v1/boats/vendor/my-boats

Transportation

Build docs developers (and LLMs) love

Overview

Listings

Transactions

Discovery

Platform Management

Documentation Index

​Vehicles

​GET /api/v1/vehicles/

​POST /api/v1/vehicles/

​GET /api/v1/vehicles/

​PUT /api/v1/vehicles/

​DELETE /api/v1/vehicles/

​Key Vehicle Fields

​GET /api/v1/vehicles/vendor/my-vehicles

​Boats

​GET /api/v1/boats/

​POST /api/v1/boats/

​GET /api/v1/boats/

​PUT /api/v1/boats/

​DELETE /api/v1/boats/

​Key Boat Fields

​GET /api/v1/boats/vendor/my-boats

​Transportation

Build docs developers (and LLMs) love

Vehicles

GET /api/v1/vehicles/

POST /api/v1/vehicles/

GET /api/v1/vehicles/

PUT /api/v1/vehicles/

DELETE /api/v1/vehicles/

Key Vehicle Fields

GET /api/v1/vehicles/vendor/my-vehicles

Boats

GET /api/v1/boats/

POST /api/v1/boats/

GET /api/v1/boats/

PUT /api/v1/boats/

DELETE /api/v1/boats/

Key Boat Fields

GET /api/v1/boats/vendor/my-boats

Transportation