{"openapi":"3.0.3","info":{"title":"Lucky Rentals AI Agent API","description":"API for AI agents to discover vehicle availability and pricing for the Lucky Rentals booking system.\n\n## Workflow\n\n1. **Discover Depots**: GET `/depots` to get available pickup/dropoff locations\n2. **Check Availability**: GET `/vehicles/availability` with dates and locations to get available vehicles\n3. **Discover Options**: For a chosen vehicle, get accessories and insurance options:\n   - GET `/vehicles/{vehicleId}/accessories`\n   - GET `/vehicles/{vehicleId}/insurance-types`\n4. **Get Quote**: GET `/quotes` with vehicle and selected options for final pricing\n5. **Direct Website Query**: AI Agents can also query vehicle availability directly on the website by appending search parameters to the `/book` URL. Example: `/book?pick_up_depot_id=1&drop_off_depot_id=1&pick_up_date=YYYY-MM-DD&drop_off_date=YYYY-MM-DD`\n","version":"1.0.0","contact":{"name":"Lucky Rentals API Support"}},"servers":[{"url":"https://www.luckyrentals.co.nz/api/agent","description":"Lucky Rentals AI Agent API"}],"paths":{"/depots":{"get":{"summary":"Get all available depot locations","description":"Returns a list of all active depot locations with their operating hours","tags":["Discovery"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Depot"}},"example":[{"id":1,"name":"Auckland Airport","pickup_times":[{"time":"09:00","day":"weekday"},{"time":"10:00","day":"weekend"}],"drop_off_times":[{"time":"17:00","day":"weekday"},{"time":"16:00","day":"weekend"}],"opening_hours_description":"Weekdays 9am-5pm, Weekends 10am-4pm"},{"id":2,"name":"Auckland City","pickup_times":[{"time":"08:00","day":"weekday"},{"time":"09:00","day":"weekend"}],"drop_off_times":[{"time":"18:00","day":"weekday"},{"time":"17:00","day":"weekend"}],"opening_hours_description":"Weekdays 8am-6pm, Weekends 9am-5pm"}]}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/vehicles/availability":{"get":{"summary":"Get available vehicles for given criteria","description":"Returns a list of vehicles available for the specified dates and locations","tags":["Discovery"],"parameters":[{"name":"pick_up_depot_id","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the pickup depot","example":1},{"name":"drop_off_depot_id","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the drop-off depot","example":2},{"name":"pick_up_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Pickup date (YYYY-MM-DD)","example":"2024-01-15"},{"name":"drop_off_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Drop-off date (YYYY-MM-DD)","example":"2024-01-22"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"example":[{"vehicleId":4,"name":"Lucky Rover Beta","rentalDailyRate":45,"imageUrl":"https://www.luckyrentals.co.nz/vehicle-type/4/image"},{"vehicleId":7,"name":"Adventure Camper Plus","rentalDailyRate":65,"imageUrl":"https://www.luckyrentals.co.nz/vehicle-type/7/image"}]}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/vehicles/{vehicleId}/accessories":{"get":{"summary":"Get accessories available for a specific vehicle","description":"Returns a list of accessories that can be added to the specified vehicle","tags":["Options Discovery"],"parameters":[{"name":"vehicleId","in":"path","required":true,"schema":{"type":"integer"},"description":"ID of the vehicle","example":4}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Accessory"}},"example":[{"id":1,"name":"Bedding Pack (for 2 people)","price":10},{"id":2,"name":"Camping Chairs (set of 2)","price":10},{"id":15,"name":"Portable BBQ","price":25},{"id":23,"name":"Outdoor Table","price":15}]}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/vehicles/{vehicleId}/insurance-types":{"get":{"summary":"Get insurance options available for a specific vehicle","description":"Returns a list of insurance plans that can be selected for the specified vehicle","tags":["Options Discovery"],"parameters":[{"name":"vehicleId","in":"path","required":true,"schema":{"type":"integer"},"description":"ID of the vehicle","example":4}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Insurance"}},"example":[{"id":1,"name":"Basic Insurance (No excess reduction)","price":0},{"id":15,"name":"\"On the Fence\" Insurance ($1500 Excess)","price":15},{"id":3,"name":"Premium Insurance ($500 Excess)","price":35}]}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/quotes":{"get":{"summary":"Get detailed price quote for vehicle configuration","x-web-checkout-template":"https://www.luckyrentals.co.nz/book?pick_up_depot_id={pick_up_depot_id}&drop_off_depot_id={drop_off_depot_id}&pick_up_date={pick_up_date}&drop_off_date={drop_off_date}&vehicle_id={vehicle_id}&insurance_id={insurance_id}&accessory_ids={accessory_ids}","description":"Returns a comprehensive price breakdown for the specified vehicle and options","tags":["Quoting"],"parameters":[{"name":"pick_up_depot_id","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the pickup depot","example":1},{"name":"drop_off_depot_id","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the drop-off depot","example":1},{"name":"pick_up_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Pickup date (YYYY-MM-DD)","example":"2025-09-17"},{"name":"drop_off_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Drop-off date (YYYY-MM-DD)","example":"2025-09-24"},{"name":"vehicle_id","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the selected vehicle","example":4},{"name":"accessory_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of accessory IDs (e.g., \"1,5,7\")","example":"1,2"},{"name":"insurance_id","in":"query","required":false,"schema":{"type":"integer"},"description":"ID of the selected insurance plan","example":15}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"},"example":{"quoteId":"1757992557279-4","expiresAt":"2025-09-16T03:45:57.279Z","currency":"NZD","priceBreakdown":{"rentalFee":360,"routeFee":0,"accessoriesFee":20,"insuranceFee":120,"accessories":[{"id":1,"name":"Bedding Pack (for 2 people)","cost":10,"quantity":1},{"id":2,"name":"Camping Chairs (set of 2)","cost":10,"quantity":1}],"insurance":{"id":15,"name":"\"On the Fence\" Insurance ($1500 Excess)","cost":120}},"totalAmount":500,"note":"All amounts are in NZD dollars. Original external API returns values in cents which are automatically converted for AI consumption."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"schemas":{"Depot":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the depot"},"name":{"type":"string","description":"Display name of the depot"},"pickup_times":{"type":"array","items":{"type":"object"},"description":"Available pickup times"},"drop_off_times":{"type":"array","items":{"type":"object"},"description":"Available drop-off times"},"opening_hours_description":{"type":"string","description":"Human-readable description of opening hours"}}},"Vehicle":{"type":"object","properties":{"vehicleId":{"type":"integer","description":"Unique identifier for the vehicle"},"name":{"type":"string","description":"Display name of the vehicle"},"rentalDailyRate":{"type":"number","format":"float","description":"Base daily rental rate"},"imageUrl":{"type":"string","format":"uri","description":"URL to vehicle image"}}},"Accessory":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the accessory"},"name":{"type":"string","description":"Display name of the accessory"},"price":{"type":"number","format":"float","description":"Price of the accessory"}}},"Insurance":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the insurance plan"},"name":{"type":"string","description":"Display name of the insurance plan"},"price":{"type":"number","format":"float","description":"Price of the insurance plan"}}},"Quote":{"type":"object","properties":{"quoteId":{"type":"string","description":"Unique identifier for this quote"},"expiresAt":{"type":"string","format":"date-time","description":"When this quote expires"},"priceBreakdown":{"type":"object","properties":{"rentalFee":{"type":"number","format":"float","description":"Base vehicle rental cost"},"accessoriesFee":{"type":"number","format":"float","description":"Total cost of selected accessories"},"insuranceFee":{"type":"number","format":"float","description":"Cost of selected insurance"},"accessories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cost":{"type":"number","format":"float"}}}},"insurance":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"cost":{"type":"number","format":"float"}}}}},"totalAmount":{"type":"number","format":"float","description":"Final total cost"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Missing required query parameter: pick_up_depot_id"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Vehicle not available for the selected criteria."}}}},"RateLimited":{"description":"Too many requests","content":{"text/plain":{"schema":{"type":"string","example":"Too Many Requests"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string"}}}},"ServiceUnavailable":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"Discovery","description":"Endpoints for discovering available options"},{"name":"Options Discovery","description":"Endpoints for discovering vehicle-specific options"},{"name":"Quoting","description":"Endpoints for generating price quotes"}]}