{"openapi":"3.0.3","info":{"title":"Droovo Carpooling API & Gemini Extension","version":"1.0.0","description":"Official API and Gemini Extension for Droovo Carpooling in Tunisia. Supports searching rides across all 24 governorates with 5-factor relevance scoring, atomic ride publishing, and real-time passenger booking with Google Auth account linking.","contact":{"name":"Droovo Support","email":"droovo.app@gmail.com","url":"https://droovo.tn"}},"servers":[{"url":"https://mcp.droovo.tn","description":"Current Deployment Server"}],"components":{"securitySchemes":{"droovoOAuth":{"type":"oauth2","description":"Droovo Google Account Linking for Gemini and AI Assistants","flows":{"authorizationCode":{"authorizationUrl":"https://mcp.droovo.tn/api/oauth/authorize","tokenUrl":"https://mcp.droovo.tn/api/oauth/token","scopes":{"rides:read":"Search rides, check seat availability, and view vehicle details","rides:write":"Book seats, publish new rides, and manage bookings"}}}},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Verified Firebase Auth ID Token"}},"schemas":{"TunisianGovernorate":{"type":"string","enum":["Ariana","Béja","Ben Arous","Bizerte","Gabès","Gafsa","Jendouba","Kairouan","Kasserine","Kébili","Kef","Mahdia","Manouba","Médenine","Monastir","Nabeul","Sfax","Sidi Bouzid","Siliana","Sousse","Tataouine","Tozeur","Tunis","Zaghouan"],"description":"One of the 24 official Tunisian governorates"},"RideOptions":{"type":"object","properties":{"hasAC":{"type":"boolean","description":"Air conditioning equipped"},"hasMusic":{"type":"boolean","description":"Music friendly ride"},"smokingAllowed":{"type":"boolean","description":"Smoking permitted"},"petsAllowed":{"type":"boolean","description":"Pets allowed in vehicle"},"autoFill":{"type":"boolean","description":"Instantly confirm bookings without driver review"},"baggageCapacity":{"type":"integer","minimum":0,"maximum":10,"description":"Baggage pieces supported"}}}}},"security":[{"droovoOAuth":["rides:read","rides:write"]},{"bearerAuth":[]}],"paths":{"/api/rides/search":{"get":{"summary":"Search Carpool Rides","description":"Find active carpool rides between Tunisian governorates with 5-factor relevance ranking. Publicly accessible without login.","security":[],"parameters":[{"name":"originGovernorate","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TunisianGovernorate"},"description":"Departure governorate"},{"name":"destinationGovernorate","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TunisianGovernorate"},"description":"Arrival governorate"},{"name":"seatsNeeded","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":4,"default":1},"description":"Number of passenger seats requested"},{"name":"departureDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Date in YYYY-MM-DD format"},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":25},"description":"Maximum price per seat in DT"}],"responses":{"200":{"description":"List of matching rides sorted by relevance score"}}}},"/api/rides/manage":{"get":{"summary":"Get Ride Details","description":"Retrieve complete ride details including seat layout and group chat info.","security":[],"parameters":[{"name":"rideId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Complete ride details"},"404":{"description":"Ride not found"}}},"post":{"summary":"Cancel or Respond to Ride Requests","description":"Consequential ride action. Drivers accept/reject applicants, passengers cancel requests.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","requestId"],"properties":{"action":{"type":"string","enum":["cancel","respond"]},"requestId":{"type":"string"},"decision":{"type":"string","enum":["accept","reject"]},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Action executed successfully"},"401":{"description":"Unauthorized"}}}},"/api/rides/publish":{"post":{"summary":"Publish a Carpool Ride","description":"Publish a ride as a verified driver. Creates ride, group chat, and reserves vehicle atomically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["carId","originGovernorate","destinationGovernorate","departureTime","passengerSeatsCount","pricePerSeat"],"properties":{"carId":{"type":"string","description":"Driver vehicle ID"},"originGovernorate":{"$ref":"#/components/schemas/TunisianGovernorate"},"destinationGovernorate":{"$ref":"#/components/schemas/TunisianGovernorate"},"originDetails":{"type":"string"},"destinationDetails":{"type":"string"},"departureTime":{"type":"string","format":"date-time"},"passengerSeatsCount":{"type":"integer","minimum":1,"maximum":4},"pricePerSeat":{"type":"number","minimum":0,"maximum":25},"options":{"$ref":"#/components/schemas/RideOptions"}}}}}},"responses":{"201":{"description":"Ride published successfully"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/api/rides/book":{"post":{"summary":"Book / Request Seats on a Ride","description":"Reserve passenger seats with live conflict checks and group chat notification.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rideId","seatsCount"],"properties":{"rideId":{"type":"string"},"seatsCount":{"type":"integer","minimum":1,"maximum":4},"baggageCount":{"type":"integer","minimum":0,"maximum":5},"pickupLocation":{"type":"string"},"dropoffLocation":{"type":"string"},"noteToDriver":{"type":"string"}}}}}},"responses":{"201":{"description":"Seats booked or request submitted"},"400":{"description":"Seats unavailable or conflict"},"401":{"description":"Unauthorized"}}}},"/api/user/profile":{"get":{"summary":"Get User Profile, Cars, or Rides","description":"Retrieve profile details, owned vehicles, or past/current rides for the authenticated user.","parameters":[{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["me","cars","rides"],"default":"me"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["driver","passenger","all"],"default":"all"}}],"responses":{"200":{"description":"User data"},"401":{"description":"Unauthorized"}}}}}}