{"openapi":"3.0.3","info":{"title":"FareHawk REST API","description":"Provider-neutral, versioned travel decision API.","version":"1.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/health/live":{"get":{"summary":"Process liveness","tags":["health"],"responses":{"200":{"description":"Default Response"}}}},"/health/ready":{"get":{"summary":"Dependency and mode readiness","tags":["health"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/magic-links":{"post":{"summary":"Request a one-time passwordless sign-in link","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/verify":{"get":{"summary":"Consume a one-time magic-link token","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/me":{"get":{"summary":"Read the current passwordless session","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/intents/resolve":{"post":{"summary":"Resolve natural language into TripIntentV1","tags":["search"],"responses":{"200":{"description":"Default Response"}}}},"/v1/searches":{"post":{"summary":"Run a bounded trip search","tags":["search"],"security":[],"responses":{"200":{"description":"Default Response"}}}},"/api/search_flights":{"post":{"operationId":"searchFlights","summary":"Search flights and return ranked plans","tags":["search"],"description":"Search-only Duffel flight search. Returns explainable ranked plans, per-traveler math, freshness, date-grid data, and affiliate disclosure.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["origin","destination","depart_date"],"properties":{"origin":{"type":"string","pattern":"^[A-Z]{3}$","description":"Origin IATA airport code."},"destination":{"type":"string","pattern":"^[A-Z]{3}$","description":"Destination IATA airport code."},"depart_date":{"type":"string","format":"date"},"return_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"adults":{"type":"integer","minimum":1,"maximum":9,"default":1},"child_ages":{"type":"array","maxItems":8,"items":{"type":"integer","minimum":0,"maximum":17},"default":[]},"cabin":{"type":"string","enum":["economy","premium_economy","business","first"],"default":"economy"},"max_stops":{"anyOf":[{"type":"integer","minimum":0,"maximum":3},{"type":"null"}],"default":1},"budget_usd":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"flexible_days":{"type":"integer","minimum":0,"maximum":3,"default":0}}}}}},"security":[],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["search_id","state","provider_mode","plans","completed_at"],"properties":{"search_id":{"type":"string"},"state":{"type":"string"},"provider_mode":{"type":"string","enum":["test","live"]},"plans":{"type":"array","items":{"type":"object","additionalProperties":true}},"date_grid":{"type":"array","items":{"type":"object","additionalProperties":true}},"destination_options":{"type":"array","items":{"type":"object","additionalProperties":true}},"completed_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}}}}},"/api/compare_plans":{"post":{"operationId":"comparePlans","summary":"Compare two or three ranked plans","tags":["search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan_ids"],"properties":{"plan_ids":{"type":"array","minItems":2,"maxItems":3,"items":{"type":"string"}}}}}}},"security":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}}}}},"/api/watches":{"post":{"operationId":"createWatch","summary":"Create an API price watch","tags":["account"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["query_snapshot","trigger","consent"],"properties":{"query_snapshot":{},"trigger":{},"consent":{"type":"boolean","enum":[true]}}}}}},"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}}}},"get":{"operationId":"listWatches","summary":"List API price watches","tags":["account"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}}}}},"/api/preferences":{"get":{"operationId":"getPreferences","summary":"Read API ranking preferences","tags":["account"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"object","additionalProperties":true}}}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"OpenAPI document for custom GPT Actions","tags":["search"],"security":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/searches/{searchId}":{"get":{"summary":"Get search progress and results","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"searchId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/searches/{searchId}/events":{"get":{"summary":"One-shot search progress event stream","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"searchId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/searches/{searchId}/cancel":{"post":{"summary":"Cancel an in-progress search","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"searchId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/plans/{planId}":{"get":{"summary":"Get one normalized plan","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"planId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/plans/compare":{"post":{"summary":"Compare distinct plans","tags":["search"],"responses":{"200":{"description":"Default Response"}}}},"/v1/plans/{planId}/booking-links":{"post":{"summary":"Create a freshly revalidated partner click-out","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"planId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/shares":{"post":{"summary":"Create an expiring privacy-safe result share","tags":["search"],"responses":{"200":{"description":"Default Response"}}}},"/v1/shares/{shareToken}":{"get":{"summary":"Read an active share","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"shareToken","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Revoke a share","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"shareToken","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/watches":{"post":{"summary":"Create a consented price watch","tags":["account"],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List current user watches","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/watches/{watchId}":{"patch":{"summary":"Pause or resume a watch","tags":["account"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"watchId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a watch","tags":["account"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"watchId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/me/preferences":{"get":{"summary":"Read consented preferences","tags":["account"],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Replace consented preferences","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/me/export":{"get":{"summary":"Export user-owned data","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/v1/me":{"delete":{"summary":"Delete and anonymize user data","tags":["account"],"responses":{"200":{"description":"Default Response"}}}},"/go/{clickId}":{"get":{"summary":"Resolve a signed partner redirect","tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"clickId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/admin/providers":{"get":{"summary":"Provider rights and health matrix","tags":["admin"],"responses":{"200":{"description":"Default Response"}}}},"/v1/admin/metrics":{"get":{"summary":"Pilot scorecard and operational metrics","tags":["admin"],"responses":{"200":{"description":"Default Response"}}}},"/v1/admin/conversions/import":{"post":{"summary":"Import an idempotent partner conversion CSV","tags":["admin"],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api-staging-ed85.up.railway.app"}],"tags":[{"name":"search"},{"name":"account"},{"name":"admin"},{"name":"health"}]}