{"openapi":"3.1.0","info":{"title":"Travelpayouts (BYOK) API","version":"0.1.0","description":"Travelpayouts (BYOK) lets an AI assistant read your own Travelpayouts data through the Travelpayouts API with a key you supply (Travelpayouts API token). Read-only: 10 tools (get_cheapest_tickets, get_nonstop_tickets, get_daily_price_calendar, get_monthly_prices, list_airline_popular_routes, list_popular_destinations, list_latest_prices, get_month_price_matrix, get_alternative_direction_prices,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-travelpayouts.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-travelpayouts/docs"},"termsOfService":"https://connectorbay.com/byok-travelpayouts/terms"},"servers":[{"url":"https://byok-travelpayouts.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-travelpayouts/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_cheapest_tickets":{"post":{"operationId":"get_cheapest_tickets","summary":"Get the cheapest cached tickets for a route, nonstop and with one or two stops, filtered by departure and return month o","description":"Get the cheapest cached tickets for a route, nonstop and with one or two stops, filtered by departure and return month or day. Use '-' as destination for all routes. Use for \"What are the cheapest flights from Moscow to Phuket in November\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example MOW.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, or '-' for all routes.","maxLength":3,"title":"Destination","type":"string"},"depart_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Departure day (YYYY-MM-DD) or month (YYYY-MM).","title":"Depart Date"},"return_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Return day (YYYY-MM-DD) or month (YYYY-MM).","title":"Return Date"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number (100 prices per page).","title":"Page"}},"required":["origin","destination"],"title":"get_cheapest_ticketsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nonstop_tickets":{"post":{"operationId":"get_nonstop_tickets","summary":"Get the cheapest cached nonstop tickets for a route, filtered by departure and return month or day. Use for \"Is there a ","description":"Get the cheapest cached nonstop tickets for a route, filtered by departure and return month or day. Use for \"Is there a cheap nonstop flight from Moscow to Saint Petersburg next month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example MOW.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, or '-' for all routes.","maxLength":3,"title":"Destination","type":"string"},"depart_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Departure day (YYYY-MM-DD) or month (YYYY-MM).","title":"Depart Date"},"return_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Return day (YYYY-MM-DD) or month (YYYY-MM).","title":"Return Date"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination"],"title":"get_nonstop_ticketsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_daily_price_calendar":{"post":{"operationId":"get_daily_price_calendar","summary":"Get the cheapest cached ticket for each day of a month on a route (nonstop or with stops). Without a return date the pri","description":"Get the cheapest cached ticket for each day of a month on a route (nonstop or with stops). Without a return date the prices are one-way. Use for \"Which days in November are cheapest to fly from Moscow to Barcelona\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example MOW.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, for example BCN.","maxLength":3,"title":"Destination","type":"string"},"depart_date":{"description":"Departure month (YYYY-MM) or day (YYYY-MM-DD).","maxLength":10,"title":"Depart Date","type":"string"},"calendar_type":{"anyOf":[{"enum":["departure_date","return_date"],"type":"string"},{"type":"null"}],"default":null,"description":"Which date the calendar is built on: departure_date or return_date.","title":"Calendar Type"},"return_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Return month or day; leave out for one-way prices.","title":"Return Date"},"length":{"anyOf":[{"maximum":365,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Length of stay in days.","title":"Length"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination","depart_date"],"title":"get_daily_price_calendarArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_monthly_prices":{"post":{"operationId":"get_monthly_prices","summary":"Get the cheapest cached ticket for each month on a route, nonstop or with stops. Use for \"Which month is cheapest to fly","description":"Get the cheapest cached ticket for each month on a route, nonstop or with stops. Use for \"Which month is cheapest to fly from Moscow to Phuket\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example MOW.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, for example HKT.","maxLength":3,"title":"Destination","type":"string"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination"],"title":"get_monthly_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_airline_popular_routes":{"post":{"operationId":"list_airline_popular_routes","summary":"List the routes an airline flies, most popular first, with a popularity score per route. Use for \"Which are Aeroflot's m","description":"List the routes an airline flies, most popular first, with a popularity score per route. Use for \"Which are Aeroflot's most popular routes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"airline_code":{"description":"IATA code of the airline, for example SU.","maxLength":3,"title":"Airline Code","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of routes.","title":"Limit"}},"required":["airline_code"],"title":"list_airline_popular_routesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_popular_destinations":{"post":{"operationId":"list_popular_destinations","summary":"List the most popular destinations from a city with the cheapest cached ticket to each. Use for \"Where do people fly mos","description":"List the most popular destinations from a city with the cheapest cached ticket to each. Use for \"Where do people fly most often from Moscow and how much is it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example MOW.","maxLength":3,"title":"Origin","type":"string"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin"],"title":"list_popular_destinationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_latest_prices":{"post":{"operationId":"list_latest_prices","summary":"List prices found by users in the last 48 hours, filtered by origin, destination, period and sort order. Without origin ","description":"List prices found by users in the last 48 hours, filtered by origin, destination, period and sort order. Without origin and destination it returns the cheapest recent tickets. Use for \"What are the cheapest fares found in the last two days from Bangkok\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"IATA city or country code of the departure place (2 to 3 letters).","title":"Origin"},"destination":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"IATA city or country code of the destination (2 to 3 letters).","title":"Destination"},"period_type":{"anyOf":[{"enum":["year","month"],"type":"string"},{"type":"null"}],"default":"year","description":"Period the tickets were found for: year (any time) or month (needs beginning_of_period).","title":"Period Type"},"beginning_of_period":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of the period, YYYY-MM-DD; required when period_type is month.","title":"Beginning Of Period"},"one_way":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for one-way tickets only, false for round trips.","title":"One Way"},"sorting":{"anyOf":[{"enum":["price","route","distance_unit_price"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: price, route (popularity) or distance_unit_price.","title":"Sorting"},"trip_class":{"anyOf":[{"maximum":2,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cabin: 0 economy, 1 business, 2 first.","title":"Trip Class"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Records per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number.","title":"Page"},"show_to_affiliates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) for only prices found through partner links, false for all prices.","title":"Show To Affiliates"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"title":"list_latest_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_month_price_matrix":{"post":{"operationId":"get_month_price_matrix","summary":"Get cached prices for each day of a month on a route, grouped by number of transfers. Use for \"What does it cost per day","description":"Get cached prices for each day of a month on a route, grouped by number of transfers. Use for \"What does it cost per day to fly from Saint Petersburg to Phuket in October\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example LED.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, for example HKT.","maxLength":3,"title":"Destination","type":"string"},"month":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of the month, YYYY-MM-DD.","title":"Month"},"show_to_affiliates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) for only prices found through partner links, false for all prices.","title":"Show To Affiliates"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination"],"title":"get_month_price_matrixArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_alternative_direction_prices":{"post":{"operationId":"get_alternative_direction_prices","summary":"Get cached prices between cities near the requested origin and destination, with optional date flexibility of up to 7 da","description":"Get cached prices between cities near the requested origin and destination, with optional date flexibility of up to 7 days. Use for \"Are flights from a nearby city to Phuket cheaper than from Saint Petersburg\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example LED.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, for example HKT.","maxLength":3,"title":"Destination","type":"string"},"depart_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Departure day (YYYY-MM-DD) or month (YYYY-MM).","title":"Depart Date"},"return_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Return day (YYYY-MM-DD) or month (YYYY-MM).","title":"Return Date"},"flexibility":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Days either side of the dates to include (0 to 7).","title":"Flexibility"},"limit":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of variants (1 to 20); 1 means only the requested points.","title":"Limit"},"show_to_affiliates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) for only prices found through partner links, false for all prices.","title":"Show To Affiliates"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination"],"title":"get_alternative_direction_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_week_price_matrix":{"post":{"operationId":"get_week_price_matrix","summary":"Get cached prices for dates close to the requested departure and return dates on a route. Use for \"What are the cheapest","description":"Get cached prices for dates close to the requested departure and return dates on a route. Use for \"What are the cheapest dates around 4 November to fly from Saint Petersburg to Phuket\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"IATA code of the departure city, for example LED.","maxLength":3,"title":"Origin","type":"string"},"destination":{"description":"IATA code of the destination city, for example HKT.","maxLength":3,"title":"Destination","type":"string"},"depart_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Departure day (YYYY-MM-DD) or month (YYYY-MM).","title":"Depart Date"},"return_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Return day (YYYY-MM-DD) or month (YYYY-MM).","title":"Return Date"},"show_to_affiliates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) for only prices found through partner links, false for all prices.","title":"Show To Affiliates"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"usd","description":"Currency of the prices, as a code such as usd, eur or rub (the API default is rub).","title":"Currency"}},"required":["origin","destination"],"title":"get_week_price_matrixArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}