upgrade-agent

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['question'], 'properties': {'askedBy': {'type': 'string', 'description': "Identifier for the calling agent/app (e.g. 'claude-cowork', 'aircanada-bot'). Used for per-partner reporting on which agents ask about their brand."}, 'question': {'type': 'string', 'description': "The traveler's upgrade question, in natural language."}, 'conversationId': {'type': 'string', 'description': "Optional stable conversation id â\x80\x94 carries the operator in play across follow-up questions (e.g. 'what about the return?')."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'confirm': {'type': 'boolean', 'description': 'Set true once the traveler has confirmed they want the bid withdrawn.'}, 'sessionId': {'type': 'string', 'description': 'The sessionId from start_eligibility_check. Optional if conversationId is passed.'}, 'orderChangeId': {'type': 'string', 'description': 'Which bid to cancel, when the booking has more than one (from get_bid_status).'}, 'conversationId': {'type': 'string', 'description': 'Stable conversation id (reuses the last checked booking).'}, 'presentationReport': {'type': 'array', 'items': {'type': 'object', 'required': ['offerId', 'shown'], 'properties': {'shown': {'type': 'boolean', 'description': 'Whether you actually presented this offer to the traveler.'}, 'reason': {'enum': ['REASON_PRICE_CEILING', 'REASON_LOW_PROBABILITY', 'REASON_PREFERENCE_CLASH'], 'type': 'string', 'description': 'Why it was filtered or deprioritized â\x80\x94 supply when shown=false (over budget â\x86\x92 REASON_PRICE_CEILING; low acceptance odds â\x86\x92 REASON_LOW_PROBABILITY; conflicts with stated preferences â\x86\x92 REASON_PREFERENCE_CLASH).'}, 'offerId': {'type': 'string', 'description': "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."}}, 'additionalProperties': False}, 'description': 'REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['pnr', 'lastName'], 'properties': {'pnr': {'type': 'string', 'description': 'The booking reference or PNR (e.g. ABC123).'}, 'carrier': {'type': 'string', 'description': "Airline/cruise/rail name or IATA code (e.g. 'SWISS' or 'LX')."}, 'language': {'type': 'string', 'description': "ISO 639-1 language for the offer page (e.g. 'fr', 'es'). Defaults to 'en'."}, 'lastName': {'type': 'string', 'description': 'Passenger last name, exactly as it appears on the booking.'}, 'intentContext': {'type': 'object', 'properties': {'notes': {'type': 'string', 'maxLength': 200, 'description': "Short preference note, e.g. 'anniversary trip, wants lie-flat'. For privacy, leave out booking references and names."}, 'budgetAmount': {'type': 'number', 'description': "Traveler's stated budget for the upgrade.", 'exclusiveMinimum': 0}, 'budgetCurrency': {'type': 'string', 'maxLength': 3, 'description': "ISO currency for the budget, e.g. 'CAD'."}, 'preferredCabin': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string'}}, 'description': "The traveler's stated shopping intent â\x80\x94 bound to the session and surfaced back so offers are presented against it.", 'additionalProperties': False}, 'conversationId': {'type': 'string', 'description': 'Optional stable conversation id â\x80\x94 lets place_bid/modify_bid reuse this booking.'}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'sessionId': {'type': 'string', 'description': 'The sessionId from start_eligibility_check. Optional if conversationId is passed.'}, 'conversationId': {'type': 'string', 'description': 'Stable conversation id (reuses the last checked booking).'}, 'presentationReport': {'type': 'array', 'items': {'type': 'object', 'required': ['offerId', 'shown'], 'properties': {'shown': {'type': 'boolean', 'description': 'Whether you actually presented this offer to the traveler.'}, 'reason': {'enum': ['REASON_PRICE_CEILING', 'REASON_LOW_PROBABILITY', 'REASON_PREFERENCE_CLASH'], 'type': 'string', 'description': 'Why it was filtered or deprioritized â\x80\x94 supply when shown=false (over budget â\x86\x92 REASON_PRICE_CEILING; low acceptance odds â\x86\x92 REASON_LOW_PROBABILITY; conflicts with stated preferences â\x86\x92 REASON_PREFERENCE_CLASH).'}, 'offerId': {'type': 'string', 'description': "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."}}, 'additionalProperties': False}, 'description': 'REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['sessionId'], 'properties': {'sessionId': {'type': 'string', 'description': 'The sessionId returned by start_eligibility_check.'}, 'conversationId': {'type': 'string', 'description': 'Optional stable conversation id â\x80\x94 lets later tools (place_bid) reuse this booking without re-passing the sessionId.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['carrier'], 'properties': {'carrier': {'type': 'string', 'description': "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'."}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'amount': {'type': 'number', 'description': 'The amount to price â\x80\x94 a bid in the offer currency, or a number of points for purchaseType POINTS. Omit for INSTANT (fixed price).'}, 'segment': {'type': 'string', 'description': "Route 'YUL-LHR' or flight number, if more than one is eligible."}, 'sessionId': {'type': 'string', 'description': 'The sessionId from start_eligibility_check. Optional if conversationId is passed.'}, 'upgradeType': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string'}, 'purchaseType': {'enum': ['BID', 'POINTS', 'INSTANT'], 'type': 'string', 'description': "BID (default), POINTS, or INSTANT (buy now at the airline's fixed price)."}, 'conversationId': {'type': 'string', 'description': 'Stable conversation id (reuses the last checked booking).'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'cabin': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string', 'description': 'Optional: limit to one target cabin.'}, 'carrier': {'type': 'string', 'description': "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier."}, 'conversationId': {'type': 'string', 'description': 'Optional stable conversation id â\x80\x94 reuses the operator in play.'}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['token'], 'properties': {'token': {'type': 'string', 'description': 'The watch token returned by start_watch.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'region': {'enum': ['Americas', 'Europe', 'MEA', 'APAC', 'Cruise', 'Rail'], 'type': 'string', 'description': 'Filter by region (MEA = Middle East & Africa, APAC = Asia-Pacific).'}, 'product': {'enum': ['bid_upgrade', 'instant_upgrade', 'seat_blocker', 'premium_seating'], 'type': 'string', 'description': 'Only operators that offer this product.'}, 'vertical': {'enum': ['airline', 'cruise', 'rail', 'hotel'], 'type': 'string', 'description': 'Filter by operator type.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'carrier': {'type': 'string', 'description': 'Operator name/IATA if known.'}, 'language': {'type': 'string', 'description': "ISO 639-1 language (default 'en')."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount'], 'properties': {'amount': {'type': 'number', 'description': 'The NEW bid amount in the offer currency.'}, 'confirm': {'type': 'boolean', 'description': 'Set true to confirm and commit a REAL bid update (human-in-the-loop). Only required once live bid submission is enabled.'}, 'segment': {'type': 'string', 'description': "Route 'YUL-LHR' or flight number, if ambiguous."}, 'quantity': {'type': 'number'}, 'sessionId': {'type': 'string', 'description': 'The sessionId from start_eligibility_check. Optional if conversationId is passed.'}, 'upgradeType': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string'}, 'conversationId': {'type': 'string', 'description': 'Stable conversation id (reuses the last checked booking).'}, 'presentationReport': {'type': 'array', 'items': {'type': 'object', 'required': ['offerId', 'shown'], 'properties': {'shown': {'type': 'boolean', 'description': 'Whether you actually presented this offer to the traveler.'}, 'reason': {'enum': ['REASON_PRICE_CEILING', 'REASON_LOW_PROBABILITY', 'REASON_PREFERENCE_CLASH'], 'type': 'string', 'description': 'Why it was filtered or deprioritized â\x80\x94 supply when shown=false (over budget â\x86\x92 REASON_PRICE_CEILING; low acceptance odds â\x86\x92 REASON_LOW_PROBABILITY; conflicts with stated preferences â\x86\x92 REASON_PREFERENCE_CLASH).'}, 'offerId': {'type': 'string', 'description': "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."}}, 'additionalProperties': False}, 'description': 'REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'partner': {'type': 'string', 'description': "Partner name, e.g. 'Air Canada'. Ignored for partner-scoped tokens (locked to their own brand)."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'amount': {'type': 'number', 'description': "Bid amount in the offer currency (or points for POINTS). OMIT for INSTANT â\x80\x94 the airline's fixed price is used automatically."}, 'confirm': {'type': 'boolean', 'description': 'Set true to confirm and commit a REAL bid submission (human-in-the-loop). Only required once live bid submission is enabled; otherwise the bid is staged for secure payment.'}, 'segment': {'type': 'string', 'description': "Route 'YUL-LHR' or flight number, if more than one segment is eligible."}, 'quantity': {'type': 'number', 'description': 'Number of seats (default 1).'}, 'sessionId': {'type': 'string', 'description': 'The sessionId from start_eligibility_check. Optional if conversationId is passed (reuses the last checked booking).'}, 'upgradeType': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string', 'description': 'Target cabin, if the booking has more than one eligible option.'}, 'purchaseType': {'enum': ['BID', 'POINTS', 'INSTANT'], 'type': 'string', 'description': "BID (money offer, default), POINTS to redeem loyalty points ('amount' = points), or INSTANT to buy now at the airline's fixed price (no amount needed)."}, 'conversationId': {'type': 'string', 'description': 'Stable conversation id used on get_eligibility_result â\x80\x94 lets you bid without re-passing the sessionId.'}, 'presentationReport': {'type': 'array', 'items': {'type': 'object', 'required': ['offerId', 'shown'], 'properties': {'shown': {'type': 'boolean', 'description': 'Whether you actually presented this offer to the traveler.'}, 'reason': {'enum': ['REASON_PRICE_CEILING', 'REASON_LOW_PROBABILITY', 'REASON_PREFERENCE_CLASH'], 'type': 'string', 'description': 'Why it was filtered or deprioritized â\x80\x94 supply when shown=false (over budget â\x86\x92 REASON_PRICE_CEILING; low acceptance odds â\x86\x92 REASON_LOW_PROBABILITY; conflicts with stated preferences â\x86\x92 REASON_PREFERENCE_CLASH).'}, 'offerId': {'type': 'string', 'description': "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."}}, 'additionalProperties': False}, 'description': 'REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount'], 'properties': {'cabin': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string', 'description': 'Optional: target cabin.'}, 'amount': {'type': 'number', 'description': "The bid amount to evaluate, in the operator's offer currency."}, 'carrier': {'type': 'string', 'description': "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier."}, 'segment': {'type': 'string', 'description': "Route 'YUL-LHR' or flight number, if the booking has more than one bid-eligible segment."}, 'sessionId': {'type': 'string', 'description': "The sessionId from start_eligibility_check â\x80\x94 unlocks the operator's LIVE bid-strength read for this exact booking and amount."}, 'conversationId': {'type': 'string', 'description': 'Optional stable conversation id â\x80\x94 reuses the operator (and checked booking) in play.'}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'origin': {'type': 'string', 'description': 'Origin city/airport (informational only â\x80\x94 not used to route-filter).'}, 'region': {'enum': ['Americas', 'Europe', 'MEA', 'APAC', 'Cruise', 'Rail'], 'type': 'string'}, 'product': {'enum': ['bid_upgrade', 'instant_upgrade', 'seat_blocker', 'premium_seating'], 'type': 'string'}, 'vertical': {'enum': ['airline', 'cruise', 'rail', 'hotel'], 'type': 'string'}, 'destination': {'type': 'string', 'description': 'Destination city/airport (informational only â\x80\x94 not used to route-filter).'}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'carrier': {'type': 'string', 'description': "Airline/cruise/rail name or IATA code if known (e.g. 'Air Canada' or 'AC')."}, 'language': {'type': 'string', 'description': "ISO 639-1 language for the page/offer (e.g. 'fr', 'es'). Defaults to 'en'."}, 'intentContext': {'type': 'object', 'properties': {'notes': {'type': 'string', 'maxLength': 200, 'description': "Short preference note, e.g. 'anniversary trip, wants lie-flat'. For privacy, leave out booking references and names."}, 'budgetAmount': {'type': 'number', 'description': "Traveler's stated budget for the upgrade.", 'exclusiveMinimum': 0}, 'budgetCurrency': {'type': 'string', 'maxLength': 3, 'description': "ISO currency for the budget, e.g. 'CAD'."}, 'preferredCabin': {'enum': ['BUSINESS', 'FIRST', 'PREMIUM_ECONOMY'], 'type': 'string'}}, 'description': "The traveler's stated shopping intent â\x80\x94 bound to the session and surfaced back so offers are presented against it.", 'additionalProperties': False}, 'travelerQuestion': {'type': 'string', 'description': "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). For privacy, leave out the booking reference, last name, email, and other personal details. Pass it whenever the traveler asked in free text â\x80\x94 it improves Upgrade Agent's answers over time."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['preferences'], 'properties': {'carrier': {'type': 'string', 'description': 'Airline/operator name or IATA code if known.'}, 'contact': {'type': 'object', 'properties': {'email': {'type': 'string'}, 'phone': {'type': 'string', 'description': 'Mobile number for SMS (E.164, e.g. +14155551234).'}, 'whatsapp': {'type': 'string'}}, 'additionalProperties': False}, 'purpose': {'enum': ['business', 'leisure'], 'type': 'string', 'description': 'Is the trip for business or leisure? Tailors the complementary experiences we surface at the destination.'}, 'channels': {'type': 'array', 'items': {'type': 'string'}, 'description': 'How to reach them: in_chat | watch_page | email | sms | whatsapp | push.'}, 'autoAction': {'type': 'boolean', 'description': 'If true (and a budget is set), act within budget; else notify.'}, 'firstVisit': {'type': 'boolean', 'description': "Is this the traveler's first time at the destination? Biases toward the classics vs off-the-beaten-path."}, 'preferences': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'rank': {'type': 'number', 'description': '1 = most wanted.'}, 'type': {'type': 'string', 'description': 'e.g. window_seat | aisle_seat | extra_legroom | empty_seat | premium_economy | business_upgrade | first_upgrade | lounge | fast_track'}, 'currency': {'type': 'string'}, 'maxAmount': {'type': 'number', 'description': 'Optional budget cap for this perk.'}}, 'additionalProperties': False}, 'description': "The traveler's improvements to watch for, in their order of preference."}, 'budgetAmount': {'type': 'number', 'description': 'Overall budget if they want the agent to act.'}, 'budgetCurrency': {'type': 'string'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {}}