{"openapi":"3.1.0","info":{"title":"AIRO Route Optimization API","summary":"Optimize delivery and field-service routes from your ERP, WMS or any system.","description":"Send orders, vehicles and a depot; get optimized routes back. Authenticate with an API key (`Authorization: Bearer airo_sk_…`). All POSTs that create work take an `Idempotency-Key`. Errors are `{\"error\": {\"code\", \"message\", \"fields\"}}`.","version":"1.0.0"},"servers":[{"url":"https://ai-route-optimization.com"}],"paths":{"/v1/optimizations":{"post":{"tags":["optimizations"],"summary":"Create an optimization","description":"Send orders, vehicles and a depot as JSON. The engine validates the data, then optimizes.\n\nReturns `202` with the optimization; poll it or receive a webhook. **`Idempotency-Key` is\nrequired**: retrying with the same key returns the same optimization and never bills twice.","operationId":"create_optimization_v1_optimizations_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizationIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Optimization V1 Optimizations Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["optimizations"],"summary":"List optimizations","operationId":"list_optimizations_v1_optimizations_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Optimizations V1 Optimizations Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/optimizations/{optimization_id}":{"get":{"tags":["optimizations"],"summary":"Get an optimization","operationId":"get_optimization_v1_optimizations__optimization_id__get","parameters":[{"name":"optimization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Optimization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Optimization V1 Optimizations  Optimization Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/optimizations/{optimization_id}/result":{"get":{"tags":["optimizations"],"summary":"Get the routes","description":"Routes in driving order with arrival times, KPIs, unassigned orders and warnings.","operationId":"get_result_v1_optimizations__optimization_id__result_get","parameters":[{"name":"optimization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Optimization Id"}},{"name":"include_path","in":"query","required":false,"schema":{"type":"boolean","description":"Include the map polyline of each route.","default":false,"title":"Include Path"},"description":"Include the map polyline of each route."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Result V1 Optimizations  Optimization Id  Result Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/optimizations/{optimization_id}/cancel":{"post":{"tags":["optimizations"],"summary":"Cancel an optimization","operationId":"cancel_v1_optimizations__optimization_id__cancel_post","parameters":[{"name":"optimization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Optimization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Cancel V1 Optimizations  Optimization Id  Cancel Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/optimizations/{optimization_id}/exports":{"post":{"tags":["optimizations"],"summary":"Create an export","description":"Driver-ready Excel/CSV. Same arguments return the same export; the link expires.","operationId":"create_export_v1_optimizations__optimization_id__exports_post","parameters":[{"name":"optimization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Optimization Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Export V1 Optimizations  Optimization Id  Exports Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"get":{"tags":["optimizations"],"summary":"List webhook endpoints","operationId":"list_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Webhooks V1 Webhooks Get"}}}}}},"post":{"tags":["optimizations"],"summary":"Register a webhook endpoint","description":"The signing secret is returned **once**. Events: `optimization.completed|failed|cancelled`.","operationId":"create_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Webhook V1 Webhooks Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}":{"delete":{"tags":["optimizations"],"summary":"Delete a webhook endpoint","operationId":"delete_webhook_v1_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/me":{"get":{"tags":["optimizations"],"summary":"Check your API key","description":"Returns the company and scopes behind the key: a cheap connectivity check.","operationId":"whoami_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Whoami V1 Me Get"}}}}}}}},"components":{"schemas":{"DepotIn":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Label"},"address":{"anyOf":[{"type":"string","maxLength":300,"minLength":5},{"type":"null"}],"title":"Address"},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"}},"additionalProperties":false,"type":"object","title":"DepotIn"},"ExportIn":{"properties":{"format":{"type":"string","enum":["xlsx","csv"],"title":"Format","default":"xlsx"},"include_driver_instructions":{"type":"boolean","title":"Include Driver Instructions","default":true}},"additionalProperties":false,"type":"object","title":"ExportIn"},"FleetIn":{"properties":{"count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Count"},"capacity":{"type":"number","maximum":1000000.0,"exclusiveMinimum":0.0,"title":"Capacity"},"shift_start":{"type":"string","title":"Shift Start","default":"08:00"},"shift_end":{"type":"string","title":"Shift End","default":"18:00"},"fixed_cost":{"type":"number","maximum":1000000.0,"minimum":0.0,"title":"Fixed Cost","default":0},"name_prefix":{"type":"string","maxLength":40,"minLength":1,"title":"Name Prefix","default":"Vehicle"}},"additionalProperties":false,"type":"object","required":["count","capacity"],"title":"FleetIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OptimizationIn":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Name"},"depot":{"$ref":"#/components/schemas/DepotIn"},"orders":{"items":{"$ref":"#/components/schemas/OrderIn"},"type":"array","maxItems":500,"minItems":1,"title":"Orders"},"vehicles":{"anyOf":[{"items":{"$ref":"#/components/schemas/VehicleIn"},"type":"array","maxItems":100,"minItems":1},{"type":"null"}],"title":"Vehicles","description":"Individual vehicles…"},"fleet":{"anyOf":[{"$ref":"#/components/schemas/FleetIn"},{"type":"null"}],"description":"…or N identical vehicles."},"options":{"$ref":"#/components/schemas/OptionsIn"}},"additionalProperties":false,"type":"object","required":["depot","orders"],"title":"OptimizationIn"},"OptionsIn":{"properties":{"strategy":{"type":"string","enum":["optimized","baseline"],"title":"Strategy","default":"optimized"},"objective":{"type":"string","enum":["distance","duration"],"title":"Objective","default":"distance"},"solver_seconds":{"anyOf":[{"type":"integer","maximum":60.0,"minimum":1.0},{"type":"null"}],"title":"Solver Seconds"}},"additionalProperties":false,"type":"object","title":"OptionsIn"},"OrderIn":{"properties":{"id":{"type":"string","maxLength":80,"minLength":1,"title":"Id","description":"Your order / stop reference."},"address":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Address"},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"City"},"region":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Region","description":"State or province."},"postal_code":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Postal Code"},"country":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Country"},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"},"demand":{"type":"number","maximum":1000000.0,"minimum":0.0,"title":"Demand","description":"Load units (same unit as capacity).","default":1},"service_minutes":{"type":"number","maximum":1440.0,"minimum":0.0,"title":"Service Minutes","default":5},"time_window_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Window Start","description":"HH:MM, 24-hour."},"time_window_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Window End","description":"HH:MM, 24-hour."},"customer":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Customer"},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Phone"},"notes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Notes"}},"additionalProperties":false,"type":"object","required":["id"],"title":"OrderIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VehicleIn":{"properties":{"id":{"type":"string","maxLength":80,"minLength":1,"title":"Id"},"capacity":{"type":"number","maximum":1000000.0,"exclusiveMinimum":0.0,"title":"Capacity"},"driver":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Driver"},"shift_start":{"type":"string","title":"Shift Start","default":"08:00"},"shift_end":{"type":"string","title":"Shift End","default":"18:00"},"fixed_cost":{"type":"number","maximum":1000000.0,"minimum":0.0,"title":"Fixed Cost","default":0}},"additionalProperties":false,"type":"object","required":["id","capacity"],"title":"VehicleIn"},"WebhookIn":{"properties":{"url":{"type":"string","maxLength":500,"title":"Url","description":"Public https URL that receives signed events."}},"additionalProperties":false,"type":"object","required":["url"],"title":"WebhookIn"}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"airo_sk_…"}}},"security":[{"ApiKey":[]}]}