{"openapi":"3.1.0","info":{"title":"QuantaRoute API","description":"Road-network delivery route optimisation for UK couriers","contact":{"name":"QuantaRoute","email":"hi@quantaroute.co.uk"},"version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/deep":{"get":{"summary":"Health Deep","operationId":"health_deep_health_deep_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/quantum/upload-csv":{"post":{"summary":"Upload Csv","operationId":"upload_csv_quantum_upload_csv_post","parameters":[{"name":"driver_name","in":"query","required":false,"schema":{"type":"string","default":"Driver","title":"Driver Name"}},{"name":"start_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Address"}},{"name":"return_to_start","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Return To Start"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_csv_quantum_upload_csv_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/routes/history":{"get":{"summary":"Route History","operationId":"route_history_routes_history_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/routes/recent":{"get":{"summary":"Recent Routes","operationId":"recent_routes_api_routes_recent_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/optimise-route":{"post":{"tags":["Agent API"],"summary":"Optimise a small delivery route","description":"Optimise 2-20 delivery stops for a UK courier or small operator, then return distance benchmarks, estimated saving, Google Maps URL, and a WhatsApp-ready driver message.","operationId":"api_optimise_route_api_optimise_route_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional during public testing. Paid/API access will require this later.","title":"X-Api-Key"},"description":"Optional during public testing. Paid/API access will require this later."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteSuccess"}}}},"400":{"description":"Invalid route input or geocoding failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteErrorResponse"}}}},"402":{"description":"Free trial ended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteErrorResponse"}}}},"401":{"description":"Invalid or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteErrorResponse"}}}},"429":{"description":"API key monthly limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteErrorResponse"}}}},"422":{"description":"Invalid JSON or schema validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOptimiseRouteErrorResponse"}}}}}}},"/quantum/route-optimise":{"post":{"summary":"Route Optimise","operationId":"route_optimise_quantum_route_optimise_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ApiClientMetadata":{"properties":{"label":{"type":"string","title":"Label"},"usage_count_current_month":{"type":"integer","title":"Usage Count Current Month"},"monthly_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Limit"}},"type":"object","required":["label","usage_count_current_month"],"title":"ApiClientMetadata"},"Body_upload_csv_quantum_upload_csv_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"}},"type":"object","required":["file"],"title":"Body_upload_csv_quantum_upload_csv_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PublicOptimiseRouteErrorResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":false},"error":{"$ref":"#/components/schemas/PublicRouteError"}},"type":"object","required":["error"],"title":"PublicOptimiseRouteErrorResponse"},"PublicOptimiseRouteRequest":{"properties":{"start":{"type":"string","minLength":1,"title":"Start","description":"Starting location, depot, home base, or first pickup point.","examples":["Plymouth, UK"]},"stops":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":2,"title":"Stops","description":"Delivery or appointment stops to reorder. Initially supports 2 to 20 stops.","examples":[["Drake Circus Shopping Centre, Plymouth","Royal William Yard, Plymouth","Plymouth Market, Plymouth","Plymouth Railway Station, Plymouth"]]},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End","description":"Optional final destination. If omitted, the route ends at the final optimised stop.","examples":["Plymouth, UK"]},"vehicle":{"type":"string","title":"Vehicle","default":"van","examples":["van"]},"optimise_for":{"type":"string","enum":["distance","time"],"title":"Optimise For","default":"distance"}},"type":"object","required":["start","stops"],"title":"PublicOptimiseRouteRequest","examples":[{"end":"Plymouth, UK","optimise_for":"distance","start":"Plymouth, UK","stops":["Drake Circus Shopping Centre, Plymouth","Royal William Yard, Plymouth","Plymouth Market, Plymouth","Plymouth Railway Station, Plymouth"],"vehicle":"van"}]},"PublicOptimiseRouteSuccess":{"properties":{"success":{"type":"boolean","title":"Success"},"input_stop_count":{"type":"integer","title":"Input Stop Count"},"ordered_stops":{"items":{"type":"string"},"type":"array","title":"Ordered Stops"},"original_distance_km":{"type":"number","title":"Original Distance Km"},"optimised_distance_km":{"type":"number","title":"Optimised Distance Km"},"distance_saved_km":{"type":"number","title":"Distance Saved Km"},"estimated_saving_percent":{"type":"number","title":"Estimated Saving Percent"},"algorithm_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm Used"},"google_maps_url":{"type":"string","title":"Google Maps Url"},"whatsapp_message":{"type":"string","title":"Whatsapp Message"},"route_sheet_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route Sheet Url"},"api_client":{"anyOf":[{"$ref":"#/components/schemas/ApiClientMetadata"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["success","input_stop_count","ordered_stops","original_distance_km","optimised_distance_km","distance_saved_km","estimated_saving_percent","google_maps_url","whatsapp_message","warnings"],"title":"PublicOptimiseRouteSuccess","example":{"algorithm_used":"exact brute force","api_client":{"label":"Example Courier Tool","monthly_limit":1000,"usage_count_current_month":12},"distance_saved_km":2.9,"estimated_saving_percent":13.2,"google_maps_url":"https://www.google.com/maps/dir/Plymouth%2C%20UK/...","input_stop_count":4,"optimised_distance_km":19.1,"ordered_stops":["Plymouth, UK","Plymouth Railway Station, Plymouth","Plymouth Market, Plymouth","Drake Circus Shopping Centre, Plymouth","Royal William Yard, Plymouth","Plymouth, UK"],"original_distance_km":22.0,"route_sheet_url":"https://quantaroute.co.uk/route-sheet/123","success":true,"warnings":["Distance estimates compare route candidates against the address order entered.","Drivers must follow live road conditions, vehicle restrictions, and professional judgement."],"whatsapp_message":"Hi Driver! Your optimised route is ready. Tap to open in Google Maps: https://www.google.com/maps/dir/..."}},"PublicRouteError":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Details"}},"type":"object","required":["code","message"],"title":"PublicRouteError"},"RouteRequest":{"properties":{"addresses":{"items":{"type":"string"},"type":"array","title":"Addresses"},"driver_name":{"type":"string","title":"Driver Name","default":"Driver"},"start_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Address"},"return_to_start":{"type":"boolean","title":"Return To Start","default":false}},"type":"object","required":["addresses"],"title":"RouteRequest"},"RouteResponse":{"properties":{"optimised_order":{"items":{"type":"integer"},"type":"array","title":"Optimised Order"},"ordered_addresses":{"items":{"type":"string"},"type":"array","title":"Ordered Addresses"},"start_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Address"},"return_to_start":{"type":"boolean","title":"Return To Start","default":false},"total_distance_km":{"type":"number","title":"Total Distance Km"},"naive_distance_km":{"type":"number","title":"Naive Distance Km"},"fuel_saving_percent":{"type":"number","title":"Fuel Saving Percent"},"original_order_distance_km":{"type":"number","title":"Original Order Distance Km"},"nearest_neighbour_distance_km":{"type":"number","title":"Nearest Neighbour Distance Km"},"final_selected_distance_km":{"type":"number","title":"Final Selected Distance Km"},"fuel_saving_percent_vs_original":{"type":"number","title":"Fuel Saving Percent Vs Original"},"maps_url":{"type":"string","title":"Maps Url"},"whatsapp_url":{"type":"string","title":"Whatsapp Url"},"route_sheet_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route Sheet Url"},"algorithm_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm Used"},"stops_count":{"type":"integer","title":"Stops Count"},"geocoded_count":{"type":"integer","title":"Geocoded Count"},"failed_addresses":{"items":{"type":"string"},"type":"array","title":"Failed Addresses"}},"type":"object","required":["optimised_order","ordered_addresses","total_distance_km","naive_distance_km","fuel_saving_percent","original_order_distance_km","nearest_neighbour_distance_km","final_selected_distance_km","fuel_saving_percent_vs_original","maps_url","whatsapp_url","stops_count","geocoded_count","failed_addresses"],"title":"RouteResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}