TravAI#

Use this skill when the user wants to search travel options or book a flight/stay through TravAI.

Source of truth#

If this skill conflicts with backend behavior, check the live OpenAPI schema:

text

https://api.travai.tech/openapi.json

Follow the live schema over this doc.

Critical notes#

• Search responses return search_id (not search_hash)
• Payment requests use method ( "CRYPTO" or "CARD") — not type
• Searches and offers expire; if any request fails with "not found" or EXPIRED_OFFER, re-run the search and use fresh IDs
• Offer IDs are unique per search — after re-running a search, you MUST use the new offer_id values from the new results; old offer IDs will not work with the new search_id
• For crypto payments, always return the exact amount, token, deposit address, and refund wallet — never round
• Changes and cancellations are not available via the API — direct users to support: https://t.me/travaiofficial or support@travai.tech

---

API base#

text

https://api.travai.tech

Authentication#

All endpoints (except sign-in and sign-up) require:

text

Authorization: Bearer {access_token}

Three ways to authenticate:

1. Sign up — new user
2. Sign in — returning user
3. Paste token — user copies from https://app.travai.tech/profile

Sign In#

text

POST /auth/signin
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret"
}

Response (200):

json

{
  "access_token": "eyJhbG...",
  "token_type": "bearer"
}

Sign Up#

text

POST /auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret",
  "first_name": "Jane",
  "last_name": "Doe"
}

Response (200):

json

{
  "message": "User created successfully",
  "access_token": "eyJhbG...",
  "token_type": "bearer"
}

Get current user#

text

GET /auth/me
Authorization: Bearer {access_token}

Response (200):

json

{
  "user_id": 1,
  "email": "user@example.com",
  "role": "customer",
  "is_active": true,
  "created_at": "2025-01-01T00:00:00",
  "currency": "USD"
}

Error responses#

Any failed request may return:

json

{ "detail": "Human-readable error description" }

Always check for detail in non-2xx responses and surface the message to the user.

---

Endpoints#

Search flights#

text

POST /searches
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "FLIGHT",
  "origin_iata": "LON",
  "destination_iata": "LIS",
  "departure_date": "2025-10-10",
  "return_date": "2025-10-17",
  "customers": [
    { "type": "ADULT" },
    { "type": "CHILD", "age": 10 }
  ]
}

FieldRequiredNotestypeyes"FLIGHT"``origin_iatayes3-letter IATA code (uppercase, e.g. "LON")destination_iatayes3-letter IATA code (uppercase, e.g. "LIS")departure_dateyesYYYY-MM-DD``return_datenoomit for one-waycustomersyesarray of CustomerAge (see below)

CustomerAge object:

FieldRequiredNotestypeno (default: ADULT)ADULT, CHILD, SENIOR, HELD_INFANT``agerequired for CHILD and HELD_INFANTinteger

Customer type rules:

• HELD_INFANT — under 2 years old
• CHILD — between 2 and 18 years old
• ADULT — default
• SENIOR — senior traveller

Response (200):

json

{
  "search_id": "abc123",
  "total_offers": 42,
  "best_offers": [ /* top 3 offers */ ]
}

FieldDescriptionsearch_idIdentifier for this search — use in all subsequent callstotal_offersTotal number of offers matching the searchbest_offersThe 3 best offers (sorted by price/quality)

Direct-flight filtering: To find direct flights, only keep offers where the total segment count across all slices equals the number of slices (i.e. 1 segment per slice = no stops).

Search stays#

text

POST /searches
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "STAY",
  "location_anchor": {
    "value": "Abu Dhabi",
    "type": "city"
  },
  "check_in_date": "2026-03-05",
  "check_out_date": "2026-03-10",
  "rooms": 1,
  "guests": 1,
  "radius_km": 50
}

FieldRequiredDefaultNotestypeyes—"STAY"``location_anchoryes—see StaysSearchAnchor belowcheck_in_dateyes—YYYY-MM-DD``check_out_dateyes—YYYY-MM-DD``roomsno11–8guestsno1number of adult guestsradius_kmno50search radius in km around the anchor

StaysSearchAnchor object:

FieldRequiredDescriptionvalueyesReference point text, e.g. "Milano", "London center", "LHR"``typeyesOne of: airport, city, city_center, region, address, place, others

Anchor type guide:

• airport — 3-letter IATA code (e.g. "LHR")
• city — city name (e.g. "Abu Dhabi")
• city_center — city centre / downtown (e.g. "London center")
• region — neighbourhood / district (e.g. "Manhattan")
• address — street address (e.g. "Via G.B. Pioda 10")
• place — landmark / point of interest (e.g. "Parque Edgar Sampaio Fontes")
• others — anything else

Response (200):

json

{
  "search_id": "def456",
  "total_offers": 15,
  "best_offers": [ /* top 3 offers */ ]
}

FieldDescriptionsearch_idIdentifier for this search — use in all subsequent callstotal_offersTotal number of offers matching the searchbest_offersThe 3 best offers

List offers#

text

GET /searches/{search_id}/offers?limit=20&offset=0
Authorization: Bearer {access_token}

ParameterRequiredDefaultDescriptionsearch_idyes (path)—search_id from POST /searches``limitno (query)20Max offers to return (1–200)offsetno (query)0Offset for pagination

Response (200):

json

{
  "total_offers": 42,
  "offers": [ /* paginated list of offer summaries */ ]
}

FieldDescriptiontotal_offersTotal number of offers for this searchoffersPaginated slice of offer summaries

Get single offer#

text

GET /searches/{search_id}/offers/{offer_id}
Authorization: Bearer {access_token}

Response (200): a single offer summary object.

Offer pricing (flights)#

text

GET /searches/{search_id}/offers/{offer_id}/pricing
Authorization: Bearer {access_token}

Path parameterDescriptionsearch_id``search_id from POST /searches``offer_idOffer ID from best_offers or the paginated offers list

Response (200): a flat offer summary dict with full pricing details (final price, segments, airlines, etc.).

Error (410): returns { "detail": "EXPIRED_OFFER" } if the offer is no longer available. When this happens, inform the user and re-run the search.

Hotel rates#

text

GET /searches/{search_id}/offers/{offer_id}/rates
Authorization: Bearer {access_token}

Path parameterDescriptionsearch_id``search_id from POST /searches``offer_idHotel offer ID from best_offers or the paginated offers list

Response (200): a list of room objects, each containing room details (name, description, size, max occupancy, photos, beds) and nested rates array with pricing, payment type, and cancellation conditions.

Rate pricing (stays)#

text

GET /searches/{search_id}/offers/{offer_id}/rates/{rate_id}/pricing
Authorization: Bearer {access_token}

Path parameterDescriptionsearch_id``search_id from POST /searches``offer_idHotel offer IDrate_idRate ID from the rates list

Response (200): a stay summary with full pricing details (total amount, currency, accommodation info, room breakdown).

Error (410): returns { "detail": "EXPIRED_OFFER" } if the rate is no longer available. When this happens, inform the user and re-run the search.

Hotel photo gallery#

text

GET /searches/{search_id}/offers/{offer_id}/photos

No authentication required. Returns an interactive HTML photo gallery for the hotel.

Path parameterDescriptionsearch_id``search_id from POST /searches``offer_idHotel offer ID

How to present to the user: Build the full gallery URL and share it as a clickable link:

text

https://api.travai.tech/searches/{search_id}/offers/{offer_id}/photos

Do not share individual photo URLs from the API response — they are CDN-signed and will not load in the browser. Always use the gallery link instead.

The gallery features keyboard navigation (arrow keys), click-to-advance, and a thumbnail strip.

Individual photos can also be accessed at /searches/{search_id}/offers/{offer_id}/photos/{index} (0-based) if needed for embedding.

List tokens#

text

GET /tokens
Authorization: Bearer {access_token}

Response (200): a flat list of supported crypto tokens. Each item represents one asset on one blockchain.

json

[
  { "assetId": "nep141:wrap.near", "blockchain": "NEAR", "symbol": "NEAR" },
  { "assetId": "nep141:usdc.near", "blockchain": "NEAR", "symbol": "USDC" },
  { "assetId": "eth:0xabc...", "blockchain": "Ethereum", "symbol": "USDC" }
]

FieldDescriptionassetIdToken identifier — use as origin_asset in a CRYPTO paymentblockchainBlockchain network the token lives onsymbolToken symbol (e.g. "NEAR", "USDC")

Token selection guidance:

• Group by blockchain when presenting to the user
• Prefer stablecoins (USDC, USDT) for payment unless the user requests otherwise
• When user asks for a specific token/network, match by symbol + blockchain
• Always confirm the exact assetId before proceeding

After the user picks a token, ask for their wallet address on that token's blockchain to use as refund_to.

Initiate payment#

text

POST /payments
Authorization: Bearer {access_token}
Content-Type: application/json

Payment methods: CRYPTO or CARD. Use the method field (not type).

CRYPTO payment

json

{
  "method": "CRYPTO",
  "origin_asset": "{assetId from GET /tokens}",
  "refund_to": "{user wallet address}",
  "offers": [ /* see offer object below */ ]
}

FieldRequiredDescriptionmethodyes"CRYPTO"``origin_assetyesassetId of the token selected by the user from GET /tokens``refund_toyesUser's wallet address on the selected token's network — refunds go here in the same currencyoffersyesSelected offers to pay for

Response (200):

json

{
  "payment_id": 123,
  "itinerary_id": 456,
  "deposit_address": "travai.near",
  "amount_in": "1000000",
  "amount_in_formatted": "1.00",
  "total_amount": 100,
  "currency": "USD"
}

FieldDescriptionpayment_idPayment identifier (use to check status via GET /payments/{payment_id})itinerary_idItinerary identifier (use to get confirmations via GET /itineraries/{itinerary_id}/offers)deposit_addressAddress to send tokens toamount_in_formattedExact amount of tokens to send — must match exactly, do not roundamount_inRaw token amount (integer string)total_amountFiat equivalent in smallest unit (cents)currencyISO currency code (e.g. "USD")

CARD payment

json

{
  "method": "CARD",
  "success_url": "https://app.travai.tech/?payment=success",
  "cancel_url": "https://app.travai.tech/?payment=cancel",
  "offers": [ /* see offer object below */ ]
}

FieldRequiredDescriptionmethodyes"CARD"``success_urlyesAlways "https://app.travai.tech/?payment=success"``cancel_urlyesAlways "https://app.travai.tech/?payment=cancel"``offersyesSelected offers to pay for

Response (200):

json

{
  "payment_id": 123,
  "itinerary_id": 456,
  "payment_url": "https://checkout.stripe.com/...",
  "total_amount": 100,
  "currency": "USD"
}

FieldDescriptionpayment_idPayment identifier (use to check status via GET /payments/{payment_id})itinerary_idItinerary identifier (use to get confirmations via GET /itineraries/{itinerary_id}/offers)payment_urlURL for the user to complete card paymenttotal_amountAmount in smallest currency unit (cents)currencyISO currency code (e.g. "USD")

Get payment status#

text

GET /payments/{payment_id}
Authorization: Bearer {access_token}

Path parameterDescriptionpayment_idPayment ID from the POST /payments response

Response (200): full payment record including status, fiat_amount, fiat_currency, token_amount, token_asset, created_at, updated_at.

Payment statuses: PENDING, PENDING_DEPOSIT, INCOMPLETE_DEPOSIT, KNOWN_DEPOSIT_TX, PROCESSING, SUCCESS, REFUNDED, FAILED, ERROR.

Get itinerary offers#

text

GET /itineraries/{itinerary_id}/offers
Authorization: Bearer {access_token}

Path parameterDescriptionitinerary_idItinerary ID from the POST /payments response

Response (200): list of itinerary offer items, each with itinerary_offer_id, type, provider, price, currency, status, booking_summary, created_at.

Offer object (inside offers array in payment request)#

json

{
  "type": "FLIGHT",
  "search_id": "abc123",
  "offer_id": "offer_xyz",
  "customers": [
    {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1989-04-23",
      "gender": "FEMALE",
      "nationality": "UA",
      "country_code": "380",
      "phone_number": "632816433",
      "title": "MS"
    }
  ]
}

FieldRequiredDescriptiontypeyes"FLIGHT" or "STAY"``search_idyessearch_id from the search stepoffer_idyes (FLIGHT)Offer ID from the search resultsrate_idyes (STAY)Rate ID from the hotel rates stepcustomersyesTraveller details (see below)

Customer object (inside offer customers array)#

FieldRequiredExamplefirst_nameyesJane``last_nameyesDoe``titleyesMR, MRS, MS, DR``genderyesMALE or FEMALE``date_of_birthyes1989-04-23 (YYYY-MM-DD)nationalityyesUA, GB, US (ISO 3166-1 alpha-2)country_codeyes380 (phone country code, no +)phone_numberyes632816433 (without country code)emailyesjane@example.com

IMPORTANT: first_name, last_name, and date_of_birth must exactly match the traveller's international passport. Always remind the user of this before collecting their details.

---

Workflow checklists#

Flight booking checklist#

1. Authenticate — sign in, sign up, or accept a pasted token
2. Gather details — origin, destination, dates, passengers
3. Search — POST /searches with type: "FLIGHT"
4. Present best offers — show price, airlines, stops, duration
5. Filter if needed — e.g. direct flights only (1 segment per slice)
6. Confirm pricing — GET /searches/{search_id}/offers/{offer_id}/pricing
7. Handle expiry — if 410, re-run search and start from step 3
8. Collect traveller details — warn about passport matching first
9. Choose payment method — crypto or card
10. If crypto — GET /tokens, present grouped by blockchain (prefer stablecoins), collect wallet address for refund
11. Create payment — POST /payments with method field
12. Present payment instructions:
    • Crypto: exact amount_in_formatted + token + deposit_address + refund wallet
    • Card: full untruncated payment_url
13. Check status if asked — GET /payments/{payment_id}

Stay booking checklist#

1. Authenticate — sign in, sign up, or accept a pasted token
2. Gather details — destination, check-in/out dates, rooms, guests
3. Search — POST /searches with type: "STAY"
4. Present best offers — show property name, price per night, rating, distance. Share the photo gallery link: https://api.travai.tech/searches/{search_id}/offers/{offer_id}/photos — do NOT share raw photo URLs
5. Get rates — immediately GET /searches/{search_id}/offers/{offer_id}/rates when user picks a hotel
6. Present rates — room type, price, amenities, cancellation policy
7. Confirm pricing — immediately GET .../rates/{rate_id}/pricing when user picks a rate
8. Handle expiry — if 410, re-run search and start from step 3
9. Collect traveller details — warn about passport matching first
10. Choose payment method — crypto or card
11. Create payment — include rate_id in offer object, use method field
12. Present payment instructions (same as flight)
13. Check status if asked — GET /payments/{payment_id}

---

Nearby Airports Database#

Many cities are served by multiple airports. Always check this mapping before searching — run parallel searches for all relevant airports and compare results.

If a city is not listed below but the user mentions a country or region, use your knowledge of IATA codes to identify all relevant airports.

Europe — Western#

City / CountryAirports (IATA)London / UKLHR, LGW, STN, LTN, LCYManchester / UKMAN, LPL (Liverpool, 1h)Edinburgh / UKEDI, GLA (Glasgow, 1h)Paris / FranceCDG, ORY, BVANice / FranceNCELyon / FranceLYSAmsterdam / NetherlandsAMS, EIN (Eindhoven), RTM (Rotterdam)Brussels / BelgiumBRU, CRL (Charleroi)Berlin / GermanyBERFrankfurt / GermanyFRA, HHN (Hahn)Munich / GermanyMUC, NUE (Nuremberg, nearby)Düsseldorf / GermanyDUS, CGN (Cologne, 1h), DTM (Dortmund)Hamburg / GermanyHAMZurich / SwitzerlandZRH, BSL (Basel), BRN (Bern)Geneva / SwitzerlandGVAVienna / AustriaVIE, BTS (Bratislava, 80km)Dublin / IrelandDUB, SNN (Shannon), ORK (Cork)

Europe — Southern#

City / CountryAirports (IATA)Milan / ItalyMXP, LIN, BGY (Bergamo)Rome / ItalyFCO, CIA (Ciampino)Naples / ItalyNAPVenice / ItalyVCE, TSF (Treviso)Florence / ItalyFLR, PSA (Pisa, 1h)Bologna / ItalyBLQCatania / SicilyCTA, PMO (Palermo)Madrid / SpainMADBarcelona / SpainBCN, GRO (Girona), REU (Reus)Malaga / SpainAGPValencia / SpainVLCSeville / SpainSVQAlicante / SpainALCPalma de Mallorca / SpainPMILisbon / PortugalLISPorto / PortugalOPOAthens / GreeceATHThessaloniki / GreeceSKGIstanbul / TurkeyIST, SAW (Sabiha Gökçen)Antalya / TurkeyAYT

Europe — Northern#

City / CountryAirports (IATA)Stockholm / SwedenARN, BMA, NYO (Skavsta), VST (Västerås)Copenhagen / DenmarkCPH, BLL (Billund), AAR (Aarhus)Oslo / NorwayOSL, TRF (Torp), RYG (Rygge)Helsinki / FinlandHEL, TMP (Tampere)Reykjavik / IcelandKEF, RKV

Europe — Eastern & Central#

City / CountryAirports (IATA)Prague / Czech RepublicPRGWarsaw / PolandWAW, WMI (Modlin)Krakow / PolandKRKGdansk / PolandGDNWroclaw / PolandWROBudapest / HungaryBUDBucharest / RomaniaOTP, BBU (Băneasa)Sofia / BulgariaSOFKyiv / UkraineKBP, IEV (Zhuliany)Belgrade / SerbiaBEGZagreb / CroatiaZAGSplit / CroatiaSPUDubrovnik / CroatiaDBVRiga / LatviaRIXVilnius / LithuaniaVNOTallinn / EstoniaTLLBratislava / SlovakiaBTS, VIE (Vienna, 60km)

Middle East#

City / CountryAirports (IATA)Dubai / UAEDXB, DWC (Al Maktoum)Abu Dhabi / UAEAUHDoha / QatarDOHRiyadh / Saudi ArabiaRUHJeddah / Saudi ArabiaJEDMuscat / OmanMCTBahrainBAHKuwaitKWIAmman / JordanAMMTel Aviv / IsraelTLVBeirut / LebanonBEYCairo / EgyptCAISharm El Sheikh / EgyptSSHHurghada / EgyptHRG

Asia — East#

City / CountryAirports (IATA)Tokyo / JapanNRT (Narita), HND (Haneda)Osaka / JapanKIX (Kansai), ITM (Itami)Seoul / South KoreaICN (Incheon), GMP (Gimpo)Beijing / ChinaPEK (Capital), PKX (Daxing)Shanghai / ChinaPVG (Pudong), SHA (Hongqiao)Guangzhou / ChinaCANShenzhen / ChinaSZXHong KongHKGTaipei / TaiwanTPE (Taoyuan), TSA (Songshan)

Asia — Southeast#

City / CountryAirports (IATA)Bangkok / ThailandBKK (Suvarnabhumi), DMK (Don Mueang)Phuket / ThailandHKTChiang Mai / ThailandCNXSingaporeSINKuala Lumpur / MalaysiaKUL, SZB (Sultan Abdul Aziz Shah)Jakarta / IndonesiaCGK (Soekarno-Hatta)Bali / IndonesiaDPSManila / PhilippinesMNLHo Chi Minh City / VietnamSGNHanoi / VietnamHANPhnom Penh / CambodiaPNHSiem Reap / CambodiaREPYangon / MyanmarRGN

Asia — South & Central#

City / CountryAirports (IATA)Delhi / IndiaDELMumbai / IndiaBOMBangalore / IndiaBLRColombo / Sri LankaCMBMaldivesMLEKathmandu / NepalKTMAlmaty / KazakhstanALATbilisi / GeorgiaTBSYerevan / ArmeniaEVNBaku / AzerbaijanGYDTashkent / UzbekistanTAS

Africa#

City / CountryAirports (IATA)Johannesburg / South AfricaJNB, HLA (Lanseria)Cape Town / South AfricaCPTNairobi / KenyaNBOAddis Ababa / EthiopiaADDCasablanca / MoroccoCMNMarrakech / MoroccoRAKTunis / TunisiaTUNLagos / NigeriaLOSAccra / GhanaACCDar es Salaam / TanzaniaDARZanzibar / TanzaniaZNZMauritiusMRU

North America#

City / CountryAirports (IATA)New York / USAJFK, EWR (Newark), LGA (LaGuardia)Los Angeles / USALAX, BUR (Burbank), LGB (Long Beach), ONT, SNA (Orange County)San Francisco / USASFO, OAK (Oakland), SJC (San Jose)Chicago / USAORD (O'Hare), MDW (Midway)Miami / USAMIA, FLL (Fort Lauderdale), PBI (West Palm Beach)Washington DC / USAIAD (Dulles), DCA (Reagan), BWI (Baltimore)Dallas / USADFW, DAL (Love Field)Houston / USAIAH, HOU (Hobby)Boston / USABOSSeattle / USASEAAtlanta / USAATLDenver / USADENLas Vegas / USALASHonolulu / USAHNLToronto / CanadaYYZ, YTZ (Billy Bishop)Montreal / CanadaYULVancouver / CanadaYVRMexico City / MexicoMEX, NLU (Felipe Ángeles)Cancun / MexicoCUN

South America#

City / CountryAirports (IATA)São Paulo / BrazilGRU (Guarulhos), CGH (Congonhas), VCP (Campinas)Rio de Janeiro / BrazilGIG (Galeão), SDU (Santos Dumont)Buenos Aires / ArgentinaEZE (Ezeiza), AEP (Aeroparque)Santiago / ChileSCLLima / PeruLIMBogota / ColombiaBOGMedellin / ColombiaMDE, EOH (Olaya Herrera)Cartagena / ColombiaCTG

Oceania#

City / CountryAirports (IATA)Sydney / AustraliaSYDMelbourne / AustraliaMEL, AVV (Avalon)Brisbane / AustraliaBNEPerth / AustraliaPERAuckland / New ZealandAKLQueenstown / New ZealandZQNFijiNAN

---

Smart Flight Search Strategy#

This is the core of intelligent search. Always follow this protocol.

Step 1 — Identify all relevant airports#

Before searching, check the Nearby Airports Database for both origin and destination. If the city has multiple airports, plan parallel searches.

Example: User says "London to Milan" — search LHR->MXP, LHR->LIN, LHR->BGY, LGW->MXP, LGW->LIN, LGW->BGY, STN->MXP, STN->BGY in parallel. Surface cheapest overall.

Step 2 — Run parallel searches#

Always launch multiple searches simultaneously using parallel tool calls:

• All relevant airport combinations
• If flexible dates: target date +/-1 day (+/-2 days if user explicitly flexible)

Flexible date matrix example (+/-1 day, 1 origin, 1 destination = 3 searches):

• departure_date - 1 day
• departure_date (requested)
• departure_date + 1 day

If user says they are flexible or "around that date", go +/-2 days (5 searches).

Step 3 — Analyse and surface best options#

After collecting all results:

1. Find the cheapest overall across all airport/date combinations — highlight it
2. Find the fastest (fewest stops, shortest duration) — highlight separately
3. Find the best value (price + duration balanced)
4. Flag anything unusual: next-day arrival, very long layover (>4h), overnight layover, short layover (<60min — warn about connection risk)

Step 4 — Auto-fallback if 0 results#

If a search returns 0 offers:

1. Immediately try adjacent dates (+/-1 day) without asking the user
2. Try nearby airports automatically
3. Only if all fallbacks return 0, inform the user and suggest alternatives

Step 5 — Proactively ask about flexibility#

After showing results, if prices are high (>$300 for short-haul, >$700 for medium-haul), proactively say:

"Prices on this date are on the higher side. Would you like me to check +/-1-2 days to find a cheaper option?"

---

Human Travel Agent Behaviours#

Act like an experienced travel agent, not a search engine.

Always flag these automatically (without being asked):#

• Next-day arrival: "Note: this flight arrives on April 18th, not April 17th — overnight layover in Copenhagen."
• Short layover (<60 min): "Warning: 45-min connection in Frankfurt is very tight — any delay on the first leg could cause a miss."
• Baggage not included: "No bags included — adding checked baggage will increase the price."
• Non-refundable: "This ticket is non-refundable and non-changeable."
• Instant payment required: "This fare requires immediate payment — price may not be held."
• Train might be better: For routes under 500-600 km where the total door-to-door time by train competes with flying (e.g. Paris-Brussels, Berlin-Amsterdam, London-Paris), proactively mention: "For this route, a train might be faster and more convenient door-to-door — though I can only book flights here."

Presentation style:#

• Lead with the cheapest option and mark it clearly
• Show a "best overall" pick that balances price, duration, and convenience — with a brief reason why
• When showing a connecting flight with a bad layover city, note it naturally: "This goes via Oslo — a bit of a detour, but it's the cheapest same-day option."
• Use conversational language alongside tables. E.g.: "I found 174 flights — here are the 3 worth looking at:"
• If the user's requested date has no good options, proactively show the best option on adjacent dates even if not asked

When searching multi-city / complex itineraries:#

• Break the trip into segments and search each independently in parallel
• Consider departure airports for return legs — e.g. if user ends in Maastricht, check BRU, EIN, AMS for return
• Always note which airport the return departs from — it may require travel time

Price intelligence:#

• If the same route shows wildly different prices across dates (e.g. Friday vs Tuesday), proactively mention: "Tuesday departures are significantly cheaper on this route — worth considering if you have flexibility."
• If baggage fees would make a "cheap" fare more expensive than a higher-priced fare with bags included, flag it: "Adding a bag to the $89 fare would bring it to ~$140 — the $125 Lufthansa fare with bags included may actually be better value."

---

Flight Results Display Format#

1. Header#

Always start with a header containing route, dates, passengers, and total offers found.

Template:

text

## [City] [IATA] -> [City] [IATA] | [Departure date] - [Return date] | [N] adults
Found [X] offers. Here are the best:

2. Result Groups#

All results are divided into three groups in strict order:

Group 1 — Cheapest Header: ### Cheapest

• 3-5 offers with lowest price, sorted ascending
• If same price — pick shortest total travel time

Group 2 — Fastest Header: ### Fastest

• 3 offers with shortest total duration (outbound + return)
• Even if already in "cheapest" — show here separately
• Sorted by duration ascending

Group 3 — Other options Header: ### Other options

• 2-3 interesting offers not in groups above
• E.g. different airline, different departure airport, good price/time balance

3. Table Format#

Round trip:

Route outDeparture -> Arrival (duration)ClassRoute backDeparture -> Arrival (duration)ClassPrice

One way:

RouteDeparture -> Arrival (duration)ClassPrice

Column rules:

Route (out / back):

• Format: City IATA -> City IATA (with city name next to each code)
• Include layovers in the chain
• If direct — mark "(direct)"
• Examples: Bangkok BKK -> Kuala Lumpur KUL -> Singapore SIN, Amsterdam AMS -> Barcelona BCN (direct)

Departure -> Arrival (duration):

• Date format: dd/mm
• Time format: hh:mm (local time)
• Duration: Xh Ym (segment duration only, not total)
• If arrival next day — add +1 after arrival time and include arrival date
• Normal example: 06/10 06:00 -> 11:25 (4h 25m)
• Next day example: 06/10 23:00 -> 06/11 03:30 +1 (4h 30m)

Class: Economy / Business / First

Price:

• With currency sign: $330.60 or EUR 298
• Lowest price in group — bold
• "Best pick" offer — mark as best pick before price

4. Caption Under Table#

After each table — one italic line with key details.

Key info to include per offer:

• Airline name
• Baggage included / not included
• Refundable / non-refundable
• Changes allowed / not allowed
• Short connection warning (under 60 min)
• Long layover warning (over 6h)
• Direct flight indicator
• Layover city

Caption template:

text

*[Airline] · baggage included · non-refundable · ...*

Next-day arrival — always use +1:

• +1 goes right after arrival time in table cell
• Always include arrival date next to it
• Example: 05/11 23:25 -> 05/12 06:25 +1

5. Summary Block#

After all tables — a summary block with:

5.1 Cheapest

text

Cheapest: [Airline] — [price]. [pros]. But: [cons].

5.2 Best pick A reasoned recommendation — not always the cheapest. Consider: direct vs layover, refund, baggage, price difference.

text

Best pick: [Airline], [route] — [price] ([difference] more). [conditions]. [One-sentence rationale].

5.3 Warnings (if any) Each warning — separate line. Must mention:

• Next-day arrival
• Short connection
• Long layover
• Baggage not included in cheap fares
• Departure from different airport

5.4 Call to action Last line — always offer to proceed to booking:

text

Want to book? Name your preferred option and I'll request exact pricing and details.

6. Language#

Always respond in the language the user is writing in. The structure stays the same regardless of language.

---

Troubleshooting#

ErrorCauseFix422 method field requiredSent type instead of method in payment requestUse "method": "CRYPTO" or "method": "CARD"``Search ... not foundSearch expired or invalid search_idRe-run POST /searches and use fresh search_id404 Offer ... not found in searchOffer ID from a different/old searchRe-run search and use offer_id values from the new results410 EXPIRED_OFFEROffer or rate is no longer availableRe-run search, pick a fresh offer, then retry422 on signupSent name instead of first_name/ last_nameUse separate first_name and last_name fieldsUnsupported tokenToken/chain mismatchCall GET /tokens and pick a valid assetIdRedirect loop on POSTTrailing-slash routing issueEnsure POST goes to /payments (no trailing slash)

---

Changes and cancellations#

Booking changes and cancellations cannot be done via the API. The user must contact support directly:

• Telegram: https://t.me/travaiofficial
• Email: support@travai.tech

Response time: within 24 hours.

When a user asks to change or cancel a booking, do not attempt any API calls — instead, direct them to one of the support channels above.

---

Support#

For any technical issues, questions, or problems with the API:

• Telegram: https://t.me/travaiofficial
• Email: support@travai.tech

We will reply within 24 hours.

---

Tips#

• Always authenticate before making API calls
• Always check the Nearby Airports Database before searching — run parallel searches for all relevant airports
• If the user gives flexible dates or "around that time", search +/-2 days automatically
• If a search returns 0 results, auto-retry with adjacent dates and nearby airports before telling the user
• Present flight offers sorted by price, but always highlight a "best overall" pick with a brief reason
• For round trips, always include both departure and return dates
• For stays, present offers highlighting price per night, rating, and proximity to the city centre
• When the user's intent is ambiguous, ask whether they need a flight, a stay, or both
• Always flag next-day arrivals, overnight layovers, short connections, and missing baggage proactively
• For short-haul routes (<600km), mention the train option even though TravAI can't book it
• For crypto payments, present the deposit info clearly and warn not to round amounts or substitute tokens