{"openapi":"3.1.0","info":{"title":"FreightLanesAI API","version":"v1","description":"Ocean, air, and multimodal freight intelligence, route analysis, commercial exposure, and disruption signals.","contact":{"email":"api@freightlanesai.com"}},"servers":[{"url":"https://api.freightlanesai.com","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key prefixed with fli_ — obtain from your account dashboard"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"originCountryCode is required"}}},"LaneIntelligenceRequest":{"type":"object","required":["originCountryCode","destinationCountryCode"],"properties":{"originCountryCode":{"type":"string","minLength":2,"maxLength":2,"example":"CN","description":"ISO 3166-1 alpha-2 origin country code"},"destinationCountryCode":{"type":"string","minLength":2,"maxLength":2,"example":"IL","description":"ISO 3166-1 alpha-2 destination country code"},"originPortUnlocode":{"type":"string","example":"CNSHA","description":"UN/LOCODE of origin port (optional)"},"destinationPortUnlocode":{"type":"string","example":"ILHFA","description":"UN/LOCODE of destination port (optional)"},"commodityQuery":{"type":"string","example":"lithium batteries","description":"Plain-language commodity search"},"hsCode":{"type":"string","example":"850760","description":"HS code (4 or 6 digit)"},"shipmentDate":{"type":"string","format":"date","example":"2026-04-15","description":"Expected shipment date (YYYY-MM-DD)"},"includeAlternatives":{"type":"boolean","default":true},"includeCommercialExposure":{"type":"boolean","default":true},"timeRangeDays":{"type":"integer","enum":[7,30,90,180],"default":30}}},"RouteIntelligenceRequest":{"allOf":[{"$ref":"#/components/schemas/LaneIntelligenceRequest"},{"required":["originPortUnlocode","destinationPortUnlocode"],"properties":{"originPortUnlocode":{"type":"string","example":"CNSHA"},"destinationPortUnlocode":{"type":"string","example":"ILHFA"}}}]}}},"paths":{"/api/v1/lane-intelligence":{"post":{"summary":"Lane Intelligence","description":"Returns ocean freight market intelligence for a country-to-country or port-to-port lane.","operationId":"laneIntelligence","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaneIntelligenceRequest"}}}},"responses":{"200":{"description":"Successful intelligence response"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key"},"422":{"description":"Insufficient data for this lane"},"429":{"description":"Monthly quota exceeded"}}}},"/api/v1/route-intelligence":{"post":{"summary":"Route Intelligence","description":"Returns detailed port-to-port ocean route analysis. Both origin and destination port UNLOCODE are required.","operationId":"routeIntelligence","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteIntelligenceRequest"}}}},"responses":{"200":{"description":"Successful route analysis response"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"429":{"description":"Quota exceeded"}}}},"/api/v1/openapi.json":{"get":{"summary":"OpenAPI Specification","description":"Returns this OpenAPI 3.1 specification.","operationId":"getOpenApiSpec","security":[],"responses":{"200":{"description":"OpenAPI JSON specification"}}}}}}