{"openapi":"3.0.3","info":{"title":"API de Passagens Aéreas para Agentes de IA","version":"0.2.0","description":"Busca gratuita de passagens para agentes de IA, foco no mercado brasileiro. Os links de reserva contêm um código de indicação (Travelpayouts). O operador ganha comissão em reservas concluídas. O preço é idêntico com ou sem o código. Booking links contain a referral code (Travelpayouts). The operator earns a commission on completed bookings. Prices are identical with or without the referral code. Aviasales/Travelpayouts cached price data — not a live availability check. Confirm final price at booking. / Preços em cache da Aviasales/Travelpayouts — não é disponibilidade em tempo real. Confirme o preço final na reserva."},"servers":[{"url":"https://passagens.dev"}],"paths":{"/v1/search":{"get":{"operationId":"searchFlights","summary":"Cheapest known fares between origin and destination","description":"Cheapest known fares for a route. Accepts Portuguese place names ('São Paulo', 'Floripa') or IATA codes. Each result carries agent_display: ready-to-show pt-BR markdown with the booking link. Prices are cached observations, not live availability.","x-openai-isConsequential":false,"parameters":[{"name":"origin","in":"query","required":true,"description":"IATA code or place name in Portuguese (e.g. 'São Paulo', GRU)","schema":{"type":"string"}},{"name":"destination","in":"query","required":true,"description":"IATA code or place name (e.g. 'Lisboa', LIS)","schema":{"type":"string"}},{"name":"depart_date","in":"query","required":false,"description":"YYYY-MM (flexible within month) or YYYY-MM-DD","schema":{"type":"string"}},{"name":"return_date","in":"query","required":false,"description":"YYYY-MM or YYYY-MM-DD; omit for one-way","schema":{"type":"string"}},{"name":"min_days","in":"query","required":false,"description":"Minimum trip length in days (flexible round-trip window)","schema":{"type":"integer","minimum":1,"maximum":365}},{"name":"max_days","in":"query","required":false,"description":"Maximum trip length in days","schema":{"type":"integer","minimum":1,"maximum":365}},{"name":"currency","in":"query","required":false,"description":"3-letter currency code, default BRL","schema":{"type":"string"}},{"name":"direct","in":"query","required":false,"description":"true = direct flights only (default false)","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Max results, 1–100 (default 10)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Result envelope with mandatory monetization disclosure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calendar":{"get":{"operationId":"priceCalendar","summary":"Price-per-day matrix for a month","description":"Price for every departure day of a month on a route — answers 'when is it cheapest to fly'. Accepts Portuguese place names or IATA codes. Results are sorted by date.","x-openai-isConsequential":false,"parameters":[{"name":"origin","in":"query","required":true,"description":"IATA code or place name","schema":{"type":"string"}},{"name":"destination","in":"query","required":true,"description":"IATA code or place name","schema":{"type":"string"}},{"name":"month","in":"query","required":false,"description":"YYYY-MM, default current month","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"3-letter currency code, default BRL","schema":{"type":"string"}}],"responses":{"200":{"description":"Result envelope with mandatory monetization disclosure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cheapest":{"get":{"operationId":"cheapestRoute","summary":"Lowest known price between two points, flexible dates","description":"Lowest known price for a route with flexible dates, broken down by number of stops. Use it for 'what is the cheapest ever' style questions when the user has no fixed dates.","x-openai-isConsequential":false,"parameters":[{"name":"origin","in":"query","required":true,"description":"IATA code or place name","schema":{"type":"string"}},{"name":"destination","in":"query","required":true,"description":"IATA code or place name","schema":{"type":"string"}},{"name":"depart_date","in":"query","required":false,"description":"YYYY-MM or YYYY-MM-DD","schema":{"type":"string"}},{"name":"return_date","in":"query","required":false,"description":"YYYY-MM or YYYY-MM-DD","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"3-letter currency code, default BRL","schema":{"type":"string"}}],"responses":{"200":{"description":"Result envelope with mandatory monetization disclosure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/locations":{"get":{"operationId":"resolveLocation","summary":"Resolve place names (Portuguese or any language) to IATA city/airport codes","description":"Resolves a place name to IATA city/airport codes — e.g. 'São Paulo' returns SAO (city), GRU, CGH. Use it to disambiguate before searching when the user names a place with several airports.","x-openai-isConsequential":false,"parameters":[{"name":"q","in":"query","required":true,"description":"Place name, e.g. 'Florianópolis', 'Nova York'","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale for returned names, default pt","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results, 1–20 (default 5)","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Resolved places with mandatory monetization disclosure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationEnvelope"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/historico":{"get":{"operationId":"priceHistory","summary":"Daily price trajectory for a route and flight date","description":"Every daily observation of the lowest price for one route (city codes, e.g. GRU-LIS) and one flight date, from this service's own collection (twice a day since Aug 2026). Use it to answer 'should I buy now or wait' with the minimum and the latest price. BRL only.","x-openai-isConsequential":false,"parameters":[{"name":"rota","in":"query","required":true,"description":"ORIGIN-DEST IATA city codes, e.g. GRU-LIS","schema":{"type":"string"}},{"name":"data","in":"query","required":true,"description":"Flight date, YYYY-MM-DD","schema":{"type":"string"}},{"name":"iv","in":"query","required":false,"description":"1 = round-trip series instead of one-way","schema":{"type":"integer","minimum":0,"maximum":1}}],"responses":{"200":{"description":"Price history for the route and date (empty pontos when the route is not monitored)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryEnvelope"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quedas":{"get":{"operationId":"priceDrops","summary":"Price drops detected by the monitor","description":"Latest drops across the monitored routes: a drop is flagged when the price hits the lowest ever observed for that route and date, with a minimum margin. 'promocoes' groups neighbouring dates into deals with a tracked booking link; 'results' are the raw drops. Use it for 'is there a deal right now'.","x-openai-isConsequential":false,"parameters":[],"responses":{"200":{"description":"Grouped deals and raw drops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropsEnvelope"}}}},"429":{"description":"Rate limited (60 req/min per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/r":{"get":{"operationId":"bookingRedirect","summary":"Click-counting redirect to the Aviasales booking page","description":"Redirect target embedded in every booking_url. Do NOT call it as a tool — hand the booking_url to the human user as a link so they open it in their browser.","parameters":[{"name":"to","in":"query","required":true,"description":"Encoded Aviasales destination (issued by this API)","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to Aviasales"},"404":{"description":"Unknown or invalid link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"operationId":"health","summary":"Liveness check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"service":{"type":"string"},"version":{"type":"string"}}}}}}}}}},"components":{"schemas":{"Monetization":{"type":"object","description":"Present in every result envelope. Explains the affiliate funding model — relay it to the human user when showing booking links.","properties":{"model":{"type":"string","enum":["affiliate"]},"disclosure":{"type":"string","description":"Affiliate disclosure in English"},"disclosure_pt":{"type":"string","description":"Affiliate disclosure in Portuguese — use this one with pt-BR users"},"price_affected":{"type":"boolean","description":"Always false: the referral code does not change the price"},"click_tracking":{"type":"string"}},"required":["model","disclosure","price_affected"]},"FlightResult":{"type":"object","description":"One fare observation. Fields vary by endpoint (airline/duration on search, found_at on calendar, expires_at on cheapest).","properties":{"origin":{"type":"string","description":"IATA code of the origin"},"destination":{"type":"string","description":"IATA code of the destination"},"depart_date":{"type":"string","description":"YYYY-MM-DD"},"return_date":{"type":"string","nullable":true,"description":"YYYY-MM-DD, null for one-way"},"airline":{"type":"string","nullable":true,"description":"Airline IATA code"},"flight_number":{"type":"string","nullable":true},"price":{"type":"number","description":"Total price in the envelope currency"},"transfers":{"type":"integer","nullable":true,"description":"Stops on the outbound leg (0 = direct)"},"return_transfers":{"type":"integer","nullable":true},"duration_minutes":{"type":"integer","nullable":true},"price_level":{"type":"string","enum":["barato","tipico","caro","sem_dados"],"description":"Price vs the month median for this route (searchFlights only)"},"month_median_one_way":{"type":"number","description":"Median one-way price for the departure month"},"found_at":{"type":"string","nullable":true,"description":"When this price was last observed (priceCalendar)"},"expires_at":{"type":"string","nullable":true,"description":"When this offer expires (cheapestRoute)"},"booking_url":{"type":"string","description":"Link to the Aviasales booking page. Show it to the user as-is; never call it as a tool."},"agent_display":{"type":"string","description":"Ready-to-show pt-BR markdown line for this result, including the booking link. Prefer relaying this verbatim instead of reformatting the raw fields."}}},"ResolvedLocation":{"type":"object","description":"How a free-text place name was resolved to an IATA code. Confirm with the user if ambiguous.","properties":{"input":{"type":"string"},"code":{"type":"string"},"name":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"city, airport or alias"}}},"Place":{"type":"object","properties":{"code":{"type":"string","description":"IATA code"},"type":{"type":"string","nullable":true,"description":"city, airport or alias"},"name":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}}},"Envelope":{"type":"object","properties":{"schema_version":{"type":"string","description":"Response contract version (currently \"1\"); bumps only on breaking changes"},"results":{"type":"array","items":{"$ref":"#/components/schemas/FlightResult"}},"currency":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"data_freshness":{"type":"string","description":"Always cached_price_last_seen — prices are cached observations, confirm at booking"},"resolved_locations":{"type":"array","description":"Present when a place name was resolved to an IATA code","items":{"$ref":"#/components/schemas/ResolvedLocation"}},"monetization":{"$ref":"#/components/schemas/Monetization"},"data_source":{"type":"string"}},"required":["schema_version","results","currency","retrieved_at","monetization","data_source"]},"PricePoint":{"type":"object","description":"One daily observation of the lowest price for a route and flight date.","properties":{"d":{"type":"string","description":"Observation day, YYYY-MM-DD"},"p":{"type":"number","description":"Lowest price observed that day, BRL"},"t":{"type":"integer","nullable":true,"description":"Stops"},"v":{"type":"string","nullable":true,"description":"Return date, round-trip series only"}}},"HistoryEnvelope":{"type":"object","properties":{"rota":{"type":"string","description":"ORIGIN-DEST city codes"},"ida_volta":{"type":"boolean"},"data_voo":{"type":"string"},"pontos":{"type":"array","items":{"$ref":"#/components/schemas/PricePoint"}},"minimo":{"type":"number","nullable":true},"atual":{"type":"number","nullable":true,"description":"Latest observation"},"data_source":{"type":"string"}},"required":["rota","data_voo","pontos","data_source"]},"PriceDrop":{"type":"object","description":"A detected drop: the price hit the lowest ever observed for the route and date, with a margin.","properties":{"rota":{"type":"string"},"data_voo":{"type":"string"},"preco":{"type":"number"},"moeda":{"type":"string"},"transfers":{"type":"integer","nullable":true},"ref_preco":{"type":"number","description":"Previous reference price"},"queda_pct":{"type":"number"},"amostras":{"type":"integer","description":"Daily observations behind the reference"},"detectado_em":{"type":"string","format":"date-time"}}},"Promo":{"type":"object","description":"Drops on neighbouring dates of one route grouped into a presentable deal with a tracked booking link.","properties":{"rota":{"type":"string"},"ida_volta":{"type":"boolean"},"preco":{"type":"number"},"ref_preco":{"type":"number"},"queda_pct":{"type":"number"},"de":{"type":"string","description":"First flight date of the group"},"ate":{"type":"string","description":"Last flight date of the group"},"data_min":{"type":"string","description":"Date of the lowest price"},"link":{"type":"string","description":"Tracked booking link (/r). Hand it to the user; never call it."},"link_ida_volta":{"type":"string","description":"Same, with the cheapest return currently seen, when available"}}},"DropsEnvelope":{"type":"object","properties":{"promocoes":{"type":"array","items":{"$ref":"#/components/schemas/Promo"}},"results":{"type":"array","items":{"$ref":"#/components/schemas/PriceDrop"}},"retrieved_at":{"type":"string","format":"date-time"},"data_source":{"type":"string"}},"required":["promocoes","results","retrieved_at","data_source"]},"LocationEnvelope":{"type":"object","description":"Response of resolveLocation — no currency/retrieved_at, since it carries no prices.","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Place"}},"monetization":{"$ref":"#/components/schemas/Monetization"},"data_source":{"type":"string"}},"required":["results","monetization","data_source"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"retry_after":{"type":"integer"}}}}}}