Server definition
- Hash
- sha256:63d374d34314723495dc0fc25615e0e8188fc67ccfd9ce7d135cac42b2c3cbe6
- What it is
- What a remote MCP server returned when asked what it offers: 63 tools
The blob, as servednamed by its sha256
{
"instructions": null,
"tools": [
{
"description": "Cancel a confirmed experience/tour booking. For traveler security, you must provide the bookingId along with the guest email address or last name.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The experience booking identifier to cancel",
"type": "string"
},
"email": {
"description": "The traveler contact email (required for verification).",
"type": "string"
},
"lastName": {
"description": "The traveler last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "cancelExperienceBooking",
"outputSchema": null
},
{
"description": "## Overview\n\nConfirms a pending extra-charge batch created by `/extra-charges/precharges`. Captures the Stripe PaymentIntent or bills the credit line, then appends the lines to the booking.\n\n## Access\n\nRequires Flights API access. Post-booking extra charges are not enabled by default — contact the MAQAMI support team to request access.\n\n## Idempotency\n\nIdempotent on `chargesId`, mirroring `POST /flights/bookings` prebookId replay:\n\n- **Already confirmed** — HTTP 200 with `data.message` and the persisted extras (no re-capture / no duplicate credit-line billing)\n- **Concurrent confirm** — HTTP 409 / `45035` while another confirm for the same `chargesId` holds the Redis lock; retry after the first completes\n\n## When to Use\n\n- After the customer confirmed the Stripe PaymentIntent (status `requires_capture` / `succeeded`), or immediately for `CREDIT` bookings\n\n## Constraints\n\n- Body only needs `chargesId` + `payment` (charge lines are encoded in `chargesId`)\n- `payment.method` must match the booking's original payment (`TRANSACTION_ID` or `CREDIT`)\n- For Stripe, `payment.transactionId` must be the id returned by precharges",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "Flight booking identifier",
"type": "string"
},
"chargesId": {
"description": "Opaque token from precharges",
"type": "string"
},
"payment": {
"additionalProperties": false,
"description": "Payment details for capturing the extra charge. method must match the booking original payment.",
"properties": {
"method": {
"enum": [
"TRANSACTION_ID",
"CREDIT"
],
"type": "string"
},
"transactionId": {
"description": "Required when method is TRANSACTION_ID; use the value from precharges",
"type": "string"
}
},
"required": [
"method"
],
"type": "object"
}
},
"required": [
"bookingId",
"chargesId",
"payment"
],
"type": "object"
},
"name": "chargeFlightExtraCharges",
"outputSchema": null
},
{
"description": "Capture Stripe payment then confirm cart with experiences-api. Cart status `completed` maps to dispatcher `PENDING_CONFIRMATION`; final `CONFIRMED` arrives via webhook. Cart status `ERROR` returns 502.\n\nPublic booking responses expose partner **sell** in `price` and partner earn in `commission` / `clientCommission`. Provider retail / invoice (`providerPayment`) is omitted.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"billing": {
"additionalProperties": false,
"properties": {
"countryCode": {
"type": "string"
},
"email": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"phoneNumber": {
"type": "string"
}
},
"required": [
"firstName",
"lastName",
"email",
"phoneNumber"
],
"type": "object"
},
"customTags": {
"additionalProperties": {},
"description": "Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$`; values are strings up to 255 characters.",
"type": "object"
},
"payment": {
"additionalProperties": false,
"properties": {
"method": {
"enum": [
"TRANSACTION_ID"
],
"type": "string"
},
"transactionId": {
"description": "Stripe transaction id from prebook. Omit to use the id stored on the prebook session.",
"type": "string"
}
},
"required": [
"method"
],
"type": "object"
},
"prebookId": {
"description": "Dispatcher prebook id from `POST /experiences/tours/{id}/prebooks`.",
"type": "string"
},
"traveler": {
"additionalProperties": false,
"properties": {
"email": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"phoneNumber": {
"type": "string"
}
},
"required": [
"firstName",
"lastName",
"email",
"phoneNumber"
],
"type": "object"
}
},
"required": [
"prebookId",
"billing",
"traveler",
"payment"
],
"type": "object"
},
"name": "createExperienceBooking",
"outputSchema": null
},
{
"description": "Poll booking status while pending confirmation or retrieve voucher after webhook confirms.\n\nPublic response omits `providerPayment` (provider retail/invoice).",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "Dispatcher booking ID returned from POST /experiences/bookings",
"type": "string"
}
},
"required": [
"bookingId"
],
"type": "object"
},
"name": "getExperienceBooking",
"outputSchema": null
},
{
"description": "## Overview\n\nPreview the refund amount and cancellation fee for a booking before committing to cancel it.\n\n## When to Use\n\n- **Cancellation confirmation screens** - Show the guest exactly what they'll be refunded\n- **Support tooling** - Check whether a booking is still cancellable before offering a refund\n\n## What You Get\n\n- **`cancellable`** - Whether the booking can currently be cancelled\n- **`policy`** - `cancellationFee`, `refundAmount`, `refundType`, `estimateConfidence`, `currency`, `sellingPrice`\n\n## Quick Start\n\nGET this endpoint with the dispatcher `bookingId` from `POST /experiences/bookings`. This does not cancel the booking - call `POST /experiences/bookings/{bookingId}/cancel` to actually cancel.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "Dispatcher booking ID returned from POST /experiences/bookings",
"type": "string"
}
},
"required": [
"bookingId"
],
"type": "object"
},
"name": "getExperienceBookingCancelPreview",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve full details for a specific tour, including description, media, inclusions, pricing context, and structured itineraries when available.\n\n## When to Use\n\n- **Product pages** - Display a tour detail view before the user selects dates\n- **Comparison** - Show full metadata when comparing activities\n- **Content enrichment** - Fetch descriptions and images for marketing surfaces\n\n## What You Get\n\n- **Complete tour profile** - Title, description, duration, and highlights\n- **Media** - Images and cover assets\n- **Practical info** - Meeting points, cancellation policy, and inclusions\n- **Structured itineraries** - Ordered days/items (`itineraries`) when the provider supplies them. `locations` are importance-ordered tags, not itinerary order.\n- **Localized pricing** - Prices in the requested currency\n\n## Quick Start\n\nProvide the tour `id` in the URL path plus required `language` and `currency` query parameters.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "getExperienceTour",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve available dates and time slots for a specific tour so users can pick when to attend.\n\n## When to Use\n\n- **Date pickers** - Populate a calendar or slot selector on the tour page\n- **Availability checks** - Confirm a tour runs on the user's travel dates\n- **Booking flow** - Gate the checkout path until a valid slot is selected\n\n## What You Get\n\n- **Available dates** - Days the tour can be booked\n- **Time slots** - Start times per date where applicable\n- **Capacity hints** - Whether slots are still bookable\n\n## Quick Start\n\nProvide the tour `id` in the URL path and the required `language` query parameter.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "getExperienceTourAvailability",
"outputSchema": null
},
{
"description": "## Overview\n\nResolve priced booking options, time slots, and required guest inputs for a selected tour date and participant mix.\n\n## When to Use\n\n- **Option/slot pickers** - Show available variants and start times for a date\n- **Live pricing** - Display authoritative slot sell totals (`pricing.totals.net` / `priceSummary.netPrice`)\n- **Checkout forms** - Collect `bookingQuestionSchema` before proceeding to payment\n\n## What You Get\n\n- **Booking options** - `optionId`, title, and `bookingQuestionSchema`\n- **Time slots** - `dateTime`, `isAvailable`, and slot-level pricing (`unitNet` / `totalNet` / `totals.net` / `priceSummary.netPrice`, plus `totals.commission` when markup applies)\n- **Participant mapping** - Uses `ticketCategory` keys from availability (e.g. `adult`, `child`)\n\n## Money semantics\n\nField names keep `*Net` from experiences-api; dispatcher marks commercial net up **in place** to partner sell. Use `slots[].pricing.totals.net` as `selection.price.amount` on prebook.\n\n## Quick Start\n\nPOST a body with `language`, `currency`, `date` (`YYYY-MM-DD`), and `participants` to `/experiences/tours/{id}/booking-options`. Use slot `pricing.totals.net` for display and checkout handoff.\n\n## Option-level `price`\n\n`options[].price.amount` is overwritten from the lowest available slot `pricing.totals.net` for the requested mix (after markup). It is not the GYG catalog from-price. Checkout still uses the chosen slot `pricing.totals.net`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"addons": {
"description": "Optional add-ons to price alongside the tour, from `GET .../availability` `addons[].id`.",
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"quantity": {
"type": "integer"
}
},
"required": [
"id",
"quantity"
],
"type": "object"
},
"type": "array"
},
"currency": {
"description": "ISO 4217 currency code for prices.",
"type": "string"
},
"date": {
"description": "Tour date to price, `YYYY-MM-DD`.",
"type": "string"
},
"language": {
"description": "ISO language code for localized content.",
"type": "string"
},
"participants": {
"additionalProperties": {},
"description": "Participant counts keyed by ticket category (age band), e.g. `adult`, `child`. Keys are lowercase and must match a `ticketCategory` returned by `GET /experiences/tours/{id}/availability` for this tour. An array (e.g. `[{\"category\":\"adult\",\"count\":2}]`) is rejected, and uppercase keys (e.g. `ADULT`) are rejected - use the exact lowercase category strings from availability.",
"type": "object"
}
},
"required": [
"language",
"currency",
"date",
"participants"
],
"type": "object"
},
"name": "getExperienceTourBookingOptions",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve normalized guest reviews and ratings for a specific tour.\n\n## When to Use\n\n- **Review sections** - Display guest feedback on tour detail pages\n- **Trust building** - Show authentic ratings before booking\n- **Decision support** - Help users evaluate tours before selecting dates\n\n## What You Get\n\n- **Guest reviews** - Review text, ratings, and dates\n- **Pagination** - `limit` and `offset` query parameters\n- **Localized content** - Reviews in the requested language where available\n\n## Quick Start\n\nProvide the tour `id` in the URL path plus required `language` and `currency` query parameters.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "getExperienceTourReviews",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve an existing flight checkout session (prebook) by ID, including any ancillary services already attached and a live catalog of remaining attachable services.\n\n## When to Use\n\n- **Resume checkout** — Reload prebook state after the user navigates away\n- **Confirm attached ancillaries** — Show selected seats/bags before final book\n- **Reuse payment intent** — Returns the stored Stripe `transactionId` / `secretKey` as-is (GET does not create or refresh a PaymentIntent)\n- **Credit balance** — Optionally include a live credit-line snapshot with `includeCreditBalance=true`\n\n## What You Get\n\n- Same core `FlightPrebookData` shape as `POST /flights/prebooks` / attach-services (journey, pricing, payment intent fields, `servicesAttachable`)\n- `booking.selectedServices` / `booking.bookedServices` when services were attached\n- Live `servicesAttachable` from the provider (not persisted)\n- Existing payment fields conserved from create/attach\n- Optional `creditLine` when `includeCreditBalance=true` (live remaining credit when the account can cover the prebook price)\n\n## Quick Start\n\nProvide the `prebookId` returned from `POST /flights/prebooks` in the URL path. Optionally pass `includeCreditBalance=true` to include credit-line availability.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"includeCreditBalance": {
"description": "When true, include credit line availability in the response when the account can cover the prebook price.",
"type": "boolean"
},
"prebookId": {
"description": "The unique prebook identifier",
"type": "string"
}
},
"required": [
"prebookId"
],
"type": "object"
},
"name": "getFlightPrebook",
"outputSchema": null
},
{
"description": "## Overview\n\nReturns the tax schema of a hotel as normalized static data, independent of the supply provider the rules were learned from. Each entry describes one tax or fee: whether it is already included in the room rate, whether it is a percentage of the rate or a fixed amount, and how fixed amounts scale (per adult and/or per night).\n\n## When to Use\n\n- **Price transparency** - Show guests which taxes and fees apply at a property\n- **Amount-due-at-property estimates** - Excluded taxes are typically collected at the hotel\n- **Tax auditing** - Compare supplier-declared taxes against the reference schema\n\n## Notes\n\n- Fixed amounts are expressed in USD\n- Percentage rates apply to the room rate (e.g. 13.5 means 13.5%)\n- The schema is learned by an offline pipeline; hotels without learned data return 404\n- When the direct (hotel-declared) source is enabled, taxes declared by the hotel in MAQAMI Cloud take precedence over learned rules and each entry carries `source`, `chargeType`, `appliedPer`, `appliedOn`, `payAtProperty` and validity dates",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"hotelId": {
"description": "Unique identifier of the hotel, in 'lp' format or numeric.",
"type": "string"
}
},
"required": [
"hotelId"
],
"type": "object"
},
"name": "getHotelTaxSchema",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve aggregated historical price index data for all hotels in a specific city. Returns average per-night prices aggregated by calendar day across all hotels in the city, providing city-level pricing trends.\n\n**⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions.\n\n**Pricing**: $0.02 per request\n\n**Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response.\n\n## When to Use\n\n- **City-level price analysis** - Analyze average pricing trends for an entire city\n- **Market research** - Compare pricing across different cities\n- **Destination pricing** - Get aggregated pricing data for a destination\n- **City pricing dashboards** - Build visualizations of city-level price trends\n\n## What You Get\n\n- **City-level aggregation** - Average prices aggregated across all hotels in the city (up to 1,000 hotels)\n- **Per-night prices** - Average price per night for each calendar day\n- **Daily aggregation** - One entry per day with aggregated pricing data\n- **Future dates only** - Only returns data for future check-in dates (defaults to today onwards)\n\n## Key Features\n\n- **Automatic hotel discovery** - Automatically finds hotels in the specified city (up to 1,000)\n- **City-level aggregation** - Prices are averaged across all hotels in the city, not per hotel\n- **Per-night pricing** - Prices are normalized to per-night rates\n- **Future-focused** - Only queries check-in dates in the future by default\n- **Flexible date ranges** - Optional date filtering with sensible defaults\n\n## Parameters\n\n- `countryCode` (required): ISO-2 country code (e.g., 'US', 'GB', 'FR')\n- `cityName` (required): City name (case-insensitive)\n- `fromDate` (optional): Start date in YYYY-MM-DD format. Defaults to today.\n- `toDate` (optional): End date in YYYY-MM-DD format. Defaults to 1 year from today.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"cityName": {
"description": "City name (case-insensitive)",
"type": "string"
},
"countryCode": {
"description": "ISO-2 country code (e.g., 'US', 'GB', 'FR')",
"type": "string"
},
"fromDate": {
"description": "Start date for the price index query in YYYY-MM-DD format. Defaults to today if not provided. Only future check-in dates are queried.",
"type": "string"
},
"toDate": {
"description": "End date for the price index query in YYYY-MM-DD format. Defaults to 1 year from today if not provided.",
"type": "string"
}
},
"required": [
"countryCode",
"cityName"
],
"type": "object"
},
"name": "getPriceIndexCity",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve historical price index data for a list of hotels. Returns average per-night prices aggregated by calendar day, allowing you to analyze pricing trends and patterns.\n\n**⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions.\n\n**Pricing**: $0.02 per request\n\n**Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response.\n\n## When to Use\n\n- **Price trend analysis** - Analyze how hotel prices change over time\n- **Price forecasting** - Use historical data to predict future pricing\n- **Market research** - Compare pricing across multiple hotels\n- **Pricing dashboards** - Build visualizations of hotel price trends\n\n## What You Get\n\n- **Per-night prices** - Average price per night for each calendar day\n- **Daily aggregation** - One entry per day with aggregated pricing data\n- **Multiple hotels** - Query up to 50 hotels in a single request\n- **Future dates only** - Only returns data for future check-in dates (defaults to today onwards)\n\n## Key Features\n\n- **Per-night pricing** - Prices are normalized to per-night rates regardless of stay duration\n- **Daily aggregation** - Each day has a single entry with the average per-night price across all stays that include that day\n- **Future-focused** - Only queries check-in dates in the future by default\n- **Flexible date ranges** - Optional date filtering with sensible defaults\n- **Hotel limit** - Maximum 50 hotel IDs per request\n\n## Parameters\n\n- `hotelIds` (required): Comma-separated list of hotel IDs. Maximum 50 hotel IDs allowed.\n- `fromDate` (optional): Start date in YYYY-MM-DD format. Defaults to today.\n- `toDate` (optional): End date in YYYY-MM-DD format. Defaults to 1 year from today.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"fromDate": {
"description": "Start date for the price index query in YYYY-MM-DD format. Defaults to today if not provided. Only future check-in dates are queried.",
"type": "string"
},
"hotelIds": {
"description": "Comma-separated list of hotel IDs to query price index data for. Maximum 50 hotel IDs allowed per request.",
"type": "string"
},
"toDate": {
"description": "End date for the price index query in YYYY-MM-DD format. Defaults to 1 year from today if not provided.",
"type": "string"
}
},
"required": [
"hotelIds"
],
"type": "object"
},
"name": "getPriceIndexHotels",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve cached public price data for a specific hotel and occupancy. This endpoint returns pricing information sourced from public booking platforms (e.g., Booking.com, Expedia) that has been pre-fetched and cached. It applies occupancy canonicalization automatically, so callers don't need to replicate that logic.\n\n**⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions.\n\n**Pricing**: $0.02 per request\n\n**Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response.\n\n## When to Use\n\n- **Price comparison** - Compare your negotiated rates against publicly available prices\n- **Rate validation** - Verify that your offered rates are competitive before displaying to end users\n- **Market intelligence** - Understand public pricing trends for specific hotels and dates\n\n## What You Get\n\n- **amount** - The best (lowest) cached public price for the stay in the specified currency\n- **nightlyAmount** - The best (lowest) nightly public price\n- **currency** - Currency code (USD)\n- **provider** - Normalized provider identifier for the best offer (e.g., `cheaptickets`)\n- **rawObservedText** - Raw observed price text from the source\n- **offers** - Public price offers from multiple booking providers\n- **fetchedAt** - When the price was last retrieved from the source\n- **expiresAt** - When this cached price expires and should no longer be used\n\n## Key Features\n\n- **Occupancy-specific** - Prices are stored per occupancy configuration; query params must match write-time occupancy\n- **Negative cache aware** - Returns 404 for both cache misses and negative cache entries (hotels with no public price found)\n- **Low latency** - Direct cache lookup, no upstream API calls\n\n## Parameters\n\n- `hotelId` (required): The MAQAMI hotel ID (e.g., `lpec902`)\n- `checkin` (required): Check-in date in YYYY-MM-DD format\n- `checkout` (required): Check-out date in YYYY-MM-DD format\n- `adults` (required): Number of adult guests\n- `childrenAges` (optional): Comma-separated ages of children (e.g., `5,8`)\n- `currency` (optional): Currency code; if present, must be `USD`",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adult guests",
"type": "integer"
},
"checkin": {
"description": "Check-in date in YYYY-MM-DD format",
"type": "string"
},
"checkout": {
"description": "Check-out date in YYYY-MM-DD format",
"type": "string"
},
"childrenAges": {
"description": "Comma-separated ages of children (e.g., '5,8'). Occupancy params must match those used at write time.",
"type": "string"
},
"currency": {
"description": "Currency code. If present, must be USD.",
"enum": [
"USD"
],
"type": "string"
},
"hotelId": {
"description": "The MAQAMI hotel ID",
"type": "string"
}
},
"required": [
"hotelId",
"checkin",
"checkout",
"adults"
],
"type": "object"
},
"name": "getPublicPrice",
"outputSchema": null
},
{
"description": "Retrieve details for a confirmed hotel booking. For traveler privacy, you must provide the bookingId along with the guest email address or last name used during booking.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The unique booking identifier (e.g. '2rSJvdDru')",
"type": "string"
},
"email": {
"description": "The guest email address used during booking (required for traveler verification).",
"type": "string"
},
"lastName": {
"description": "The guest last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "get_bookings_bookingid",
"outputSchema": null
},
{
"description": "## Overview\n\nGet all available hotel chains (e.g., Marriott, Hilton, IHG). Use chain IDs to filter hotel searches by brand.\n\n## When to Use\n\n- **Chain filters** - Filter hotels by chain/brand\n- **Brand selection** - Let users search for specific hotel chains\n- **Reference data** - Get chain IDs for use in search filters\n\n## What You Get\n\n- **Chain list** - All available hotel chains\n- **Chain IDs** - Numeric IDs for use in search filters\n- **Chain names** - Hotel chain/brand names\n\n## Quick Start\n\nNo parameters required. Returns all hotel chains with IDs. Use chain IDs in hotel search filters.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "get_data_chains",
"outputSchema": null
},
{
"description": "## Overview\n\nGet a list of all cities within a specific country. Perfect for building location dropdowns and city selection interfaces.\n\n## When to Use\n\n- **City dropdowns** - Populate city selection lists\n- **Location filters** - Filter hotels by city\n- **Geographic data** - Get city lists for specific countries\n- **Form autocomplete** - Build city autocomplete features\n\n## What You Get\n\n- **City list** - All cities in the specified country\n- **City names** - Formatted city names ready for display\n\n## Quick Start\n\nProvide the `countryCode` in ISO-2 format (e.g., \"US\", \"GB\"). Returns all cities in that country. Use the [Get Country List endpoint](/v3.0.0/reference/get_data-countries) to get country codes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"countryCode": {
"description": "Country code in iso-2 format (example: SG)",
"type": "string"
},
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"required": [
"countryCode"
],
"type": "object"
},
"name": "get_data_cities",
"outputSchema": null
},
{
"description": "## Overview\n\nGet a complete list of all countries available in the system with their ISO-2 country codes. Essential for building country selection interfaces.\n\n## When to Use\n\n- **Country dropdowns** - Populate country selection lists\n- **Location filters** - Filter hotels or searches by country\n- **Form inputs** - Build country selection forms\n- **Reference data** - Get country codes for use in other endpoints\n\n## What You Get\n\n- **Country list** - All available countries\n- **ISO-2 codes** - Standard country codes (e.g., \"US\", \"GB\", \"FR\")\n- **Country names** - Full country names\n\n## Quick Start\n\nNo parameters required. Returns all countries with their ISO-2 codes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"type": "object"
},
"name": "get_data_countries",
"outputSchema": null
},
{
"description": "## Overview\n\nGet all available currencies with their codes, names, and the countries where each currency is used. Perfect for building currency selection interfaces.\n\n## When to Use\n\n- **Currency dropdowns** - Populate currency selection lists\n- **Price display** - Show prices in different currencies\n- **Currency conversion** - Get currency information for conversion\n- **Reference data** - Get currency codes for use in booking endpoints\n\n## What You Get\n\n- **Currency list** - All available currencies\n- **Currency codes** - ISO currency codes (e.g., \"USD\", \"EUR\", \"GBP\")\n- **Currency names** - Full currency names\n- **Country mapping** - Countries where each currency is used\n\n## Quick Start\n\nNo parameters required. Returns all currencies with codes, names, and country mappings.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"type": "object"
},
"name": "get_data_currencies",
"outputSchema": null
},
{
"description": "## Overview\n\nGet all available hotel facilities (amenities) with multi-language translations. Use these facility IDs to filter hotel searches by amenities.\n\n## When to Use\n\n- **Facility filters** - Build amenity filtering in hotel searches\n- **Facility display** - Show available facilities with translated names\n- **Multi-language support** - Display facilities in user's language\n- **Reference data** - Get facility IDs for use in search filters\n\n## What You Get\n\n- **Facility list** - All available hotel facilities\n- **Facility IDs** - Numeric IDs for use in search filters\n- **Multi-language names** - Facility names in multiple languages\n- **Translations** - Localized facility names\n\n## Quick Start\n\nNo parameters required. Returns all facilities with IDs and multi-language translations. Use facility IDs in hotel search filters.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "get_data_facilities",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve a list of airlines with optional filtering by name, alliance, and active status.\n\n## When to Use\n\n- **Airline directory** - Build a searchable list of airlines for display or filtering\n- **Alliance filtering** - Filter airlines by alliance membership (Star Alliance, oneworld, SkyTeam)\n- **Active airlines** - Retrieve only currently operating airlines\n\n## What You Get\n\n- **Full airline records** including name, IATA/ICAO codes, country, alliance, and logo URL\n- **Alliance membership** for each airline\n- **Active status** to identify currently operating carriers\n- **Filtered results** based on query, alliance, and active status parameters\n\n## Quick Start\n\nCall with no parameters to get all airlines. Use `q` to search by name, `alliance` to filter by alliance, and `activeOnly=true` to exclude inactive carriers.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"activeOnly": {
"description": "Only return currently active airlines",
"type": "boolean"
},
"alliance": {
"description": "Filter by airline alliance",
"enum": [
"star_alliance",
"oneworld",
"skyteam",
"vanilla_alliance"
],
"type": "string"
},
"limit": {
"description": "Maximum number of results",
"type": "integer"
},
"q": {
"description": "Search query (e.g., 'AA' or 'American')",
"type": "string"
}
},
"type": "object"
},
"name": "get_data_flights_airlines",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve a lightweight list of airline IATA codes with names for autocomplete and lookup purposes.\n\n## When to Use\n\n- **Autocomplete dropdowns** - Populate airline search inputs with a minimal list\n- **Client-side filtering** - Download the full list once and filter locally\n- **Code validation** - Build a lookup table of valid airline codes\n\n## What You Get\n\n- **IATA codes** for all airlines in the database\n- **Airline names** paired with each code\n- **Active filtering** available via the `activeOnly` parameter\n\n## Quick Start\n\nCall with no parameters to get all airline IATA codes and names. Use `activeOnly=true` to filter out inactive airlines.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"activeOnly": {
"description": "Only return currently active airlines",
"type": "boolean"
}
},
"type": "object"
},
"name": "get_data_flights_airlines_iatas",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve full details for a specific airline using its 2-letter IATA code.\n\n## When to Use\n\n- **Airline display** - Show airline name, logo, and alliance for a given IATA code\n- **Flight result enrichment** - Fetch airline details to display alongside search results\n- **Data validation** - Verify an airline code and retrieve its metadata\n\n## What You Get\n\n- **Airline details** including name, IATA/ICAO codes, and country\n- **Alliance membership** (Star Alliance, oneworld, SkyTeam, or Vanilla Alliance)\n- **Logo URL** for displaying the airline's logo in your UI\n- **Active status** indicating whether the airline is currently operating\n\n## Quick Start\n\nProvide the 2-letter IATA code (e.g., `AA` for American Airlines) in the URL path.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"iataCode": {
"description": "2-letter IATA airline code (e.g., AA)",
"type": "string"
}
},
"required": [
"iataCode"
],
"type": "object"
},
"name": "get_data_flights_airlines_iatas_iatacode",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch for airports by name, city, or IATA code using a text query. Returns matching airports for use in autocomplete and search inputs.\n\n## When to Use\n\n- **Airport autocomplete** - Power origin/destination search inputs with type-ahead suggestions\n- **Airport discovery** - Find airports in a city or region by name\n- **Search validation** - Look up airports before constructing a flight search request\n\n## What You Get\n\n- **Matching airports** ranked by relevance to the query\n- **IATA codes** for `legs[].origin` and `legs[].destination` on `POST /flights/rates`\n- **City and country** details for display purposes\n- **Geographic coordinates** for map-based interfaces\n\n## Quick Start\n\nProvide a `q` query string (minimum 2 characters) to search by airport name, city, or code. Returns matching airports ordered by relevance.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"q": {
"description": "Search query (minimum 2 characters, e.g., 'JFK' or 'New York')",
"type": "string"
}
},
"required": [
"q"
],
"type": "object"
},
"name": "get_data_flights_airports",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve a lightweight list of airport IATA codes with names for autocomplete and lookup purposes.\n\n## When to Use\n\n- **Autocomplete dropdowns** - Populate airport search inputs with a full list of codes and names\n- **Client-side filtering** - Download the full list once and filter locally\n- **Code validation** - Build a lookup table of valid airport codes\n\n## What You Get\n\n- **IATA codes** for all airports in the database\n- **Airport names** paired with each code\n- **Filtered results** when the `q` query parameter is provided\n\n## Quick Start\n\nCall with no parameters to get all airport codes and names. Use the `q` parameter to filter by name or code.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"q": {
"description": "Search query",
"type": "string"
}
},
"required": [
"q"
],
"type": "object"
},
"name": "get_data_flights_airports_iatas",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve detailed information for a specific airport using its 3-letter IATA code.\n\n## When to Use\n\n- **Airport display** - Show airport name, city, and country for a given IATA code\n- **Flight result enrichment** - Fetch airport details to display alongside origin/destination in search results\n- **Autocomplete validation** - Verify an airport code and retrieve its full details\n\n## What You Get\n\n- **Airport details** including name, city, country, and timezone\n- **IATA and ICAO codes** for the airport\n- **Geographic coordinates** (latitude and longitude)\n- **Country and city** information for display purposes\n\n## Quick Start\n\nProvide the 3-letter IATA code (e.g., `JFK` for John F. Kennedy International) in the URL path.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"iataCode": {
"description": "3-letter IATA airport code (e.g., JFK)",
"type": "string"
}
},
"required": [
"iataCode"
],
"type": "object"
},
"name": "get_data_flights_airports_iatas_iatacode",
"outputSchema": null
},
{
"description": "## Overview\n\nGet comprehensive details about a specific hotel including descriptions, amenities, images, location, and ratings. Perfect for displaying hotel detail pages.\n\n## When to Use\n\n- **Hotel detail pages** - Show complete hotel information\n- **Booking pages** - Display hotel details before booking\n- **Hotel profiles** - Build rich hotel information pages\n- **Content display** - Show descriptions, amenities, and images\n\n## What You Get\n\n- **Complete hotel information** - Name, address, description, and ratings\n- **Amenities list** - All available facilities and services\n- **Image gallery** - Hotel photos and images\n- **Location details** - Address, coordinates, and location information\n- **Hotel metadata** - Star rating, chain information, and classifications\n\n## Quick Start\n\nProvide the `hotelId` as a query parameter. Returns complete hotel details including all metadata, amenities, and images.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"advancedAccessibilityOnly": {
"description": "If `true`, accessibility section will be returned",
"type": "boolean"
},
"hotelId": {
"description": "Unique ID of a hotel",
"type": "string"
},
"language": {
"description": "The language code, indicating in which language the results should be returned. e.g. 'fr'",
"type": "string"
},
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"required": [
"hotelId"
],
"type": "object"
},
"name": "get_data_hotel",
"outputSchema": null
},
{
"description": "## Overview\n\n**Beta Feature** - Ask natural language questions about a specific hotel and get AI-powered answers based on the hotel's information.\n\n## When to Use\n\n- **Hotel Q&A** - Answer customer questions about hotels\n- **Information lookup** - Get specific details about amenities, services, or features\n- **Conversational interfaces** - Build chat interfaces for hotel information\n- **Detailed inquiries** - Ask about specific aspects like restaurants, parking, or amenities\n\n## What You Get\n\n- **AI-generated answers** - Relevant responses to your questions\n- **Hotel-specific information** - Answers based on the hotel's actual data\n- **Natural language responses** - Human-readable answers\n\n## Example Questions\n\n- \"What amenities does this hotel have?\"\n- \"Is there parking available?\"\n- \"What does a meal at the restaurant look like?\"\n\n## Key Features\n\n- **Web search option** - Enable `allowWebSearch` to get additional information from the web\n- **Hotel context** - Answers are specific to the hotel you're asking about\n- **Natural language** - Ask questions conversationally\n\n## Quick Start\n\nProvide the `hotelId` and your `question`. Optionally enable `allowWebSearch` for web-enhanced answers.\n\n**Note:** This is a beta feature and may be subject to changes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"allowWebSearch": {
"description": "Whether to allow web search for additional information. Default is false.",
"type": "boolean"
},
"hotelId": {
"description": "Unique ID of the hotel (MAQAMI format)",
"type": "string"
},
"query": {
"description": "The question to ask about the hotel",
"type": "string"
}
},
"required": [
"hotelId",
"query"
],
"type": "object"
},
"name": "get_data_hotel_ask",
"outputSchema": null
},
{
"description": "Search for a hotel using a semantic text query. Returns the best-matching hotel with basic details and a relevance score.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"query": {
"description": "The semantic search query (e.g. 'Burj Jumeirah Dubai').",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "get_data_hotel_search",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch and retrieve hotel listings based on various criteria. Get hotel metadata including names, addresses, ratings, amenities, and images for display in your application.\n\n## When to Use\n\n- **Hotel listings** - Display hotel search results\n- **Location-based search** - Find hotels by city, coordinates, or Place ID\n- **Hotel discovery** - Browse hotels in specific areas\n- **Metadata retrieval** - Get hotel information for display\n\n## What You Get\n\n- **Hotel list** - Matching hotels with complete metadata\n- **Basic information** - Names, addresses, ratings, and locations\n- **Amenities** - Available facilities and features\n- **Images** - Hotel photos for display\n- **Identifiers** - Hotel IDs for use in rate searches\n\n## Search Options\n\n- **By city** - Search hotels in a specific city\n- **By coordinates** - Find hotels near latitude/longitude with radius\n- **By Place ID** - Get hotels within a specific place boundary\n- **By hotel IDs** - Retrieve specific hotels by their IDs\n\n## Quick Start\n\nProvide search criteria (city, coordinates+radius, placeId, or hotelIds). Returns matching hotels with complete metadata.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"advancedAccessibilityOnly": {
"description": "If `true`, only hotels with advanced accessibility will be returned",
"type": "boolean"
},
"aiSearch": {
"description": "Search term for AI search. Uses semantic search to find hotels matching the query intent. Examples: 'Romantic getaway with Italian vibes in London near the London Eye', 'Hotels near the Eiffel tower'",
"type": "string"
},
"chainIds": {
"description": "Comma-separated list of hotel chain ids. e.g. '14675,14677'",
"type": "string"
},
"cityName": {
"description": "Name of the city",
"type": "string"
},
"countryCode": {
"description": "Country code ISO-2 code - example (SG)",
"type": "string"
},
"facilityIds": {
"description": "Comma-separated list of facilities. e.g. '1,2,3'",
"type": "string"
},
"hotelIds": {
"description": "Comma-separated list of hotel IDs (e.g., 'lp1897,lp1343') to fetch specific hotels by their IDs. This is a valid main query parameter that can be used instead of other search criteria.",
"type": "string"
},
"hotelName": {
"description": "Name of the hotel (loose match, case-insensitive, e.g. 'hilton')",
"type": "string"
},
"hotelTypeIds": {
"description": "Comma-separated list of hotel types. e.g. '201,204,208'",
"type": "string"
},
"language": {
"description": "The language code, indicating in which language the results should be returned. e.g. 'fr'",
"type": "string"
},
"lastUpdatedAt": {
"description": "Retrieve only the hotels that have been updated since the provided date and time (using the RFC3339 format)",
"type": "string"
},
"latitude": {
"description": "Latitude geo coordinates",
"type": "number"
},
"limit": {
"description": "Specifies the maximum number of results to return. By default, this is set to 200, even if not explicitly defined. If a higher limit is specified, the maximum allowed is 5000 results",
"type": "integer"
},
"longitude": {
"description": "Longitude geo coordinates",
"type": "number"
},
"minRating": {
"description": "Minimum rating of the hotel. e.g. 8.6",
"type": "number"
},
"minReviewsCount": {
"description": "Minimum number of reviews. e.g. 100",
"type": "number"
},
"offset": {
"description": "Specifies the number of rows to skip before starting to return rows",
"type": "integer"
},
"placeId": {
"description": "Unique ID of a place retrieved from the `/data/places` endpoint. When provided, the API fetches place details and searches for hotels within a 1km radius of the place location center, or a specific hotel when the placeId refers to a property. The response includes a `place` object containing the place information used in the search.",
"type": "string"
},
"radius": {
"description": "radius in meters (min 1000m)",
"type": "integer"
},
"starRating": {
"description": "Comma-separated list of star ratings. Note: star ratings have 2 allowed decimals '.0' and '.5' from 1 to 5. e.g. '3.5,4.0,5.0'",
"type": "string"
},
"strictFacilitiesFiltering": {
"description": "If `true`, only hotels with all the specified facilities will be returned",
"type": "boolean"
},
"timeout": {
"description": "request timeout in seconds",
"type": "number"
},
"zip": {
"description": "ZIP code of the location",
"type": "string"
}
},
"type": "object"
},
"name": "get_data_hotels",
"outputSchema": null
},
{
"description": "## Overview\n\n**Beta Feature** - Search hotel rooms using visual and text-based queries. Uses image search technology to match your query against room images and find hotels with rooms that match your visual preferences, amenities, or style.\n\n## When to Use\n\n- **Visual room search** - Find rooms based on visual characteristics like \"luxury modernist comfort\" or \"blue accessible bathroom\"\n- **Style-based search** - Search for rooms by design style like \"art deco hotel room\" or \"brutalist room\"\n- **Amenity-focused search** - Find rooms with specific features like \"twin room with a city view\" or \"room with a skylight\"\n- **Geographic filtering** - Limit results to hotels near a specific location using coordinates or Place ID\n- **City and country filtering** - Filter results by city and/or country\n\n## What You Get\n\n- **Matching hotels** - Hotels grouped by hotel ID with rooms that match your query\n- **Room details** - Room name, image URL, and similarity score (rounded to 3 decimals) for each matching room\n- **Hotel metadata** - ID, name, address, city, country, and rating for each hotel\n- **Geographic filtering** - Optionally limit results to a specific area using coordinates or Place ID\n- **City and country filters** - Filter results by city and/or country code\n\n## Example Queries\n\n- \"luxury modernist comfort\"\n- \"an extremely fun room or art deco hotel room\"\n- \"luxurious accessible bathroom or blue accessible bathroom with walk in shower\"\n- \"twin room with a city view\"\n- \"a room filled with paintings\"\n- \"a hotel room with a skylight\"\n\n## Geographic Filtering\n\nYou can optionally limit search results to a specific geographic area:\n\n- **Using coordinates**: Provide `latitude`, `longitude`, and optionally `radius` (in kilometers, default: 12km)\n- **Using Place ID**: Provide `placeId` - the place's location will be automatically fetched and the search will use the place's viewport boundaries (or the provided `radius` if viewport is unavailable)\n- **Using city/country**: Provide `city` and/or `country` to filter results by location\n\n## Quick Start\n\nProvide a `query` parameter describing the room you're looking for. Optionally add geographic filtering with `latitude`/`longitude` or `placeId` to limit results to a specific area.\n\n**Note:** This is a beta feature and may be subject to changes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"city": {
"description": "Filter results by city name. Can be used alone or together with country.",
"type": "string"
},
"country": {
"description": "Filter results by country code (ISO 3166-1 alpha-2 format, e.g., 'FR', 'US'). Can be used alone or together with city.",
"type": "string"
},
"latitude": {
"description": "Latitude coordinate for geographic filtering. Must be provided together with longitude. Ignored if placeId is provided.",
"type": "number"
},
"limit": {
"description": "Maximum number of results to return (maps to top_k in the API)",
"type": "integer"
},
"longitude": {
"description": "Longitude coordinate for geographic filtering. Must be provided together with latitude. Ignored if placeId is provided.",
"type": "number"
},
"placeId": {
"description": "Place ID. If provided, the search will be limited to hotels within the place's viewport boundaries (or the provided `radius` if viewport is unavailable). The place's latitude and longitude will be automatically fetched.",
"type": "string"
},
"query": {
"description": "Search query describing the room you're looking for. Can be visual (e.g., 'luxury modernist comfort', 'blue accessible bathroom'), amenity-based (e.g., 'twin room with a city view'), or style-based (e.g., 'art deco hotel room', 'brutalist room')",
"type": "string"
},
"radius": {
"description": "Search radius in kilometers. Only used when latitude/longitude is provided, or when placeId is provided but the place does not have viewport information. When placeId is provided and viewport is available, the viewport boundaries are used instead of this radius. Default is 12km.",
"type": "number"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "get_data_hotels_room_search",
"outputSchema": null
},
{
"description": "## Overview\n\n**Beta Feature** - Search hotels using natural language queries. Uses AI to understand search intent and find hotels that match the meaning, not just keywords.\n\n## When to Use\n\n- **Natural language search** - Let users search with phrases like \"romantic getaway in London\"\n- **Intent-based matching** - Find hotels matching the vibe or style, not just location\n- **Conversational search** - Support natural language hotel discovery\n- **Semantic matching** - Get hotels that semantically match the query\n\n## What You Get\n\n- **Matching hotels** - Hotels that semantically match your query\n- **Semantic attributes** - Tags, persona, style, location_type, and story for each hotel\n- **Relevance scores** - How well each hotel matches the query\n- **Hotel metadata** - ID, name, photos, address, city, country\n\n## Example Queries\n\n- \"Romantic getaway in London with Italian vibes\"\n- \"Hotels near Paris\"\n- \"Family-friendly beachfront hotels\"\n\n## Quick Start\n\nProvide a natural language `query` parameter. Returns hotels with semantic matching scores and attributes.\n\n**Note:** This is a beta feature and may be subject to changes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"limit": {
"description": "Maximum number of results to return. Default is 3.",
"type": "integer"
},
"min_rating": {
"description": "Minimum hotel rating to filter results. Default is 0 (no minimum rating filter).",
"type": "number"
},
"query": {
"description": "Semantic search query. This can be a natural language description of what you're looking for, e.g. 'romantic getaway in london with italian vibes'",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "get_data_hotels_semantic_search",
"outputSchema": null
},
{
"description": "## Overview\n\nGet all available hotel type classifications (e.g., resort, boutique, business hotel). Use type IDs to filter hotel searches.\n\n## When to Use\n\n- **Type filters** - Filter hotels by type in search\n- **Type display** - Show hotel type classifications\n- **Reference data** - Get hotel type IDs for filtering\n\n## What You Get\n\n- **Hotel type list** - All available hotel types\n- **Type IDs** - Numeric IDs for use in search filters\n- **Type names** - Hotel type classifications\n\n## Quick Start\n\nNo parameters required. Returns all hotel types with IDs. Use type IDs in hotel search filters.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "get_data_hoteltypes",
"outputSchema": null
},
{
"description": "## Overview\n\nGet IATA (International Air Transport Association) airport codes with airport names, coordinates, and country information. Useful for airport-based hotel searches.\n\n## When to Use\n\n- **Airport searches** - Find hotels near airports\n- **Location selection** - Let users search by airport codes\n- **Geographic data** - Get airport locations and coordinates\n- **Reference data** - Get IATA codes for use in hotel searches\n\n## What You Get\n\n- **Airport list** - All available airports with IATA codes\n- **Airport names** - Full airport names\n- **Coordinates** - Latitude and longitude for each airport\n- **Country codes** - ISO-2 country codes for each airport\n\n## Quick Start\n\nNo parameters required. Returns all airports with IATA codes, names, coordinates, and country information.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"type": "object"
},
"name": "get_data_iatacodes",
"outputSchema": null
},
{
"description": "## Overview\n\nGet all supported languages for hotel translations and content localization. Use language codes to request hotel data in specific languages.\n\n## When to Use\n\n- **Language selection** - Display available languages to users\n- **Content localization** - Get language codes for API requests\n- **Multi-language support** - Build language switchers in your application\n- **Reference data** - Validate language codes before making requests\n\n## What You Get\n\n- **Language list** - All supported and enabled languages\n- **Language codes** - ISO 639-1 codes (e.g., 'en', 'es', 'fr')\n- **Language names** - Human-readable language names in English\n\n## Quick Start\n\nNo parameters required. Returns all supported languages with codes and names. Use language codes in hotel search and detail requests.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "get_data_languages",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch for places, locations, and areas using Google Places API. Returns a list of matching places that can be used to search for hotels within specific boundaries.\n\n**Pricing**: $0.01 per request\n\n## When to Use\n\n- **Location autocomplete** - Build location search with autocomplete suggestions\n- **Place selection** - Let users select cities, airports, or areas\n- **Hotel search boundaries** - Get Place IDs to restrict hotel searches to specific regions\n- **Location discovery** - Find places by name or description\n\n## What You Get\n\n- **Place list** - Multiple matching places with details\n- **Place IDs** - Unique identifiers for use in hotel searches\n- **Location information** - Names, addresses, and location types\n- **Formatted addresses** - Human-readable addresses for display\n\n## Key Features\n\n- **Multiple types** - Search for cities, airports, hotels, or other place types\n- **Type filtering** - Specify place types (e.g., 'locality,airport,hotel')\n- **Smart defaults** - Automatically excludes less relevant types unless specified\n- **Relevance ordering** - Results sorted by relevance using Google's ranking\n\n## Quick Start\n\nProvide a `textQuery` (e.g., \"Manhattan\") and optionally specify `type` to filter results. Returns matching places with Place IDs you can use in hotel searches.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"clientIP": {
"description": "The IP address of the client making the request.",
"type": "string"
},
"language": {
"description": "The language code, indicating in which language the results should be returned. e.g. 'en'",
"type": "string"
},
"sessionId": {
"description": "Optional Google Places billing session ID. When provided, this autocomplete call is bundled into a session settled by a subsequent place details call, reducing billing costs. Can also be passed via the X-Places-Session-Id header (header takes priority). If omitted, the server manages a fallback session automatically.",
"type": "string"
},
"textQuery": {
"description": "Search query. e.g. 'Manhattan'",
"type": "string"
},
"type": {
"description": "Restricts the results to places matching the specified type(s). You can specify a single type (e.g., 'hotel') or multiple types as a comma-separated list (e.g., 'locality,airport,hotel'). Common types include: 'locality' (cities), 'airport', 'hotel', 'lodging', 'establishment', 'point_of_interest'. When multiple types are provided, results from all types are merged and ordered by relevance.",
"type": "string"
}
},
"required": [
"textQuery"
],
"type": "object"
},
"name": "get_data_places",
"outputSchema": null
},
{
"description": "## Overview\n\nGet detailed information about a specific place using its Place ID. Returns complete place details including boundaries and location information.\n\n**Pricing**: $0.01 per request\n\n## When to Use\n\n- **Place details** - Get full information about a selected place\n- **Boundary information** - Retrieve place boundaries for hotel searches\n- **Location verification** - Verify place details before using in searches\n- **Display information** - Show place names and addresses to users\n\n## What You Get\n\n- **Complete place details** - Full information about the place\n- **Boundary data** - Geographic boundaries for the place\n- **Location information** - Coordinates, address, and display name\n- **Place metadata** - Types, formatted address, and language\n\n## Quick Start\n\nProvide the `placeId` in the URL path. Returns complete details for that specific place.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"language": {
"description": "The language code, indicating in which language the results should be returned. e.g. 'en'",
"type": "string"
},
"placeId": {
"description": "Unique identifier of the place to retrieve.",
"type": "string"
},
"sessionId": {
"description": "Optional Google Places billing session ID. Pass the same value used in the preceding autocomplete calls to settle the billing session, making those autocomplete calls free. Can also be passed via the X-Places-Session-Id header (header takes priority).",
"type": "string"
}
},
"required": [
"placeId"
],
"type": "object"
},
"name": "get_data_places_placeid",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve guest reviews and ratings for a specific hotel. Display authentic feedback from previous guests to help users make informed booking decisions.\n\n## When to Use\n\n- **Review display** - Show guest reviews on hotel detail pages\n- **Rating aggregation** - Display average ratings and review counts\n- **Trust building** - Show authentic guest feedback\n- **Decision support** - Help users evaluate hotels before booking\n\n## What You Get\n\n- **Guest reviews** - Individual review text and ratings\n- **Review dates** - When each review was written\n- **Ratings** - Numerical and textual ratings\n- **Guest feedback** - Detailed comments from previous guests\n\n## Quick Start\n\nProvide the `hotelId` as a query parameter. Returns all reviews for that hotel with ratings and comments.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"getSentiment": {
"description": "If set to true, an AI sentiment analysis of the last 1000 reviews will be returned",
"type": "boolean"
},
"hotelId": {
"description": "Unique ID of a hotel",
"type": "string"
},
"language": {
"description": "ISO 639-1 language code (e.g., 'fr', 'es', 'de') to translate reviews using AI. If not provided, the reviews will be returned in the default language (en). When this parameter is provided, the maximum number of reviews returned is 10.",
"type": "string"
},
"limit": {
"description": "Specifies the maximum number of results to return. By default, this is set to 200, even if not explicitly defined. If a higher limit is specified, the maximum allowed is 5000 results",
"type": "integer"
},
"offset": {
"description": "Specifies the number of reviews to skip, defaults to 0",
"type": "integer"
},
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"required": [
"hotelId"
],
"type": "object"
},
"name": "get_data_reviews",
"outputSchema": null
},
{
"description": "## Overview\n\nGet weather forecasts for specific locations. Response structure adapts based on the forecast time range (short-term vs. long-term).\n\n## When to Use\n\n- **Travel planning** - Show weather forecasts for destinations\n- **Hotel pages** - Display weather information on hotel detail pages\n- **Trip preparation** - Help users plan for weather conditions\n- **Destination information** - Provide weather context for locations\n\n## What You Get\n\n- **Weather forecasts** - Temperature, humidity, wind, precipitation\n- **Time-based structure** - Different formats for short-term (<1 week) vs. long-term forecasts\n- **Detailed data** - Atmospheric pressure, conditions, and summaries\n- **Date-specific** - Weather data for specific dates\n\n## Key Features\n\n- **Adaptive structure** - Response format changes based on time range\n- **Short-term** - Detailed hourly/daily data for forecasts within one week\n- **Long-term** - Daily summaries for forecasts beyond one week\n- **Accuracy note** - Forecasts beyond one week have reduced accuracy\n\n## Quick Start\n\nProvide location coordinates (`latitude`, `longitude`) and date range. Returns weather forecasts with appropriate detail level.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"endDate": {
"description": "End date in YYYY-MM-DD format. The service can provide future forecasts, but reliability significantly decreases beyond one week.",
"type": "string"
},
"latitude": {
"description": "Latitude of the location.",
"type": "string"
},
"longitude": {
"description": "Longitude of the location.",
"type": "string"
},
"startDate": {
"description": "Start date in YYYY-MM-DD format. The service can provide future forecasts, but reliability significantly decreases beyond one week.",
"type": "string"
},
"units": {
"description": "Units of measurement. Default is metric.",
"enum": [
"metric",
"imperial"
],
"type": "string"
}
},
"required": [
"latitude",
"longitude",
"startDate",
"endDate"
],
"type": "object"
},
"name": "get_data_weather",
"outputSchema": null
},
{
"description": "Retrieve complete details of a confirmed flight booking. For traveler privacy, you must provide the bookingId along with the passenger email address or last name.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The unique flight booking identifier",
"type": "string"
},
"email": {
"description": "The passenger contact email (required for verification).",
"type": "string"
},
"lastName": {
"description": "The passenger last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "get_flights_bookings_bookingid",
"outputSchema": null
},
{
"description": "## Overview\n\nReturns refund eligibility, estimated refund amounts, and penalty details for a booking **without actually cancelling it**. Use this before calling `POST /flights/bookings/{bookingId}/cancellations` to understand the financial impact of cancellation.\n\n## When to Use\n\n- **Pre-cancellation review** — Show the customer the potential maximum refund (not guaranteed) before they confirm cancellation\n- **Refund estimation** — Display potential maximum refund and penalty amounts in the booking management UI (refund is not granted until cancel completes)\n- **Eligibility check** — Determine whether the booking is within the void window (`isVoidable`) or eligible for a partial refund (`isRefundable`)\n\n## What You Get\n\n- **`confidence`** — How reliable the quote is (`confirmed`, `estimated`, `heuristic`, `unknown`)\n- **`isRefundable` / `isVoidable`** — Quick eligibility flags\n- **`refund` / `penalty`** — Aggregate amounts with margin applied. `refund` is the potential maximum the airline may refund — not a granted/guaranteed amount\n- **`penalties[]`** — Itemised penalty breakdown when available\n- **`tickets[]`** — Per-ticket detail when available\n- **`destination`** — Where refunded money goes (`original_payment`, `agency_deposit`, `voucher`, etc.)\n- **`vouchers[]`** — Airline travel vouchers / credit-shells when `destination` is `voucher`; omitted when absent. Distinct from MAQAMI discount `voucherCode` on prebook\n\n## Concurrent cancellation\n\nIf a cancellation was already submitted and is still awaiting provider confirmation, this endpoint returns **HTTP 409** with code `49007` (`CONCURRENT_OPERATION`). A new quote is not available until that cancellation completes or fails.\n\n## Refund amount caveat\n\nThe `refund` amount on a cancellation quote is the **potential maximum** the airline may refund if cancellation proceeds under the quoted conditions. It is an estimate for decision-making only and is **not granted** — the final refund (if any) is determined when cancellation completes and may be lower or zero. The refund may arrive asynchronously once the airline determines the final amount.\n\n## Key Features\n\n- **Non-destructive** — Does not cancel the booking; safe to call before user confirmation\n- **Margin-applied pricing** — All amounts (including voucher `pricing.display`) reflect the same margin applied at booking time\n\n## Quick Start\n\nProvide the `bookingId` from `POST /flights/bookings` in the URL path. Every call hits the upstream provider — do not place this on a hot polling loop.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The unique booking identifier",
"type": "string"
}
},
"required": [
"bookingId"
],
"type": "object"
},
"name": "get_flights_bookings_bookingid_cancellations",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve the ancillary services (seats, baggage) for an existing flight booking: services that are **already booked** together with the live catalog of services that **can still be booked**.\n\n## When to Use\n\n- **Post-booking upsell** - Show the passenger which seats and bags they can still add after the booking was created\n- **Booking management** - Display the services already attached to the booking with the prices that were charged\n- **Availability refresh** - The bookable catalog is fetched live from the provider on every call\n\n## What You Get\n\n- **`groups`** - Bookable services grouped by category (seat, baggage) with post-margin prices and encoded `serviceId`s\n- **`bookedServices`** - Services already attached to the booking; entries booked through the API carry the exact price that was charged at attach time\n- **`expiresAt`** - Validity window of the bookable catalog\n\n## Key Features\n\n- **Read-only**: Safe to call at any time; the catalog reflects live availability\n- **Consistent pricing**: Booked services echo the post-margin amounts the user actually paid\n\n## Quick Start\n\nProvide the `bookingId` (returned from `POST /flights/bookings`) in the URL path.\n\n> **Note:** Booking additional services on an existing booking is not available yet; this endpoint currently only reports availability.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The unique booking identifier",
"type": "string"
}
},
"required": [
"bookingId"
],
"type": "object"
},
"name": "get_flights_bookings_bookingid_services",
"outputSchema": null
},
{
"description": "## Overview\n\nRetrieve details of an existing prebook session by its ID. Use this to fetch prebook information without creating a new session.\n\n## When to Use\n\n- **Session recovery** - Retrieve prebook details if you've stored the prebookId\n- **Status checks** - Verify prebook session details before completing booking\n- **Payment integration** - Get prebook data needed for payment processing\n- **Credit balance** - Optionally include updated credit balance information\n\n## What You Get\n\n- **Complete prebook data** - All information from the prebook session\n- **Rate details** - Pricing, room types, and availability\n- **Terms and conditions** - Cancellation policies and booking terms\n- **Credit balance** - Optional updated credit balance (if requested)\n\n## Quick Start\n\nProvide the `prebookId` in the URL path. Optionally include `includeCreditBalance` query parameter to get updated credit information.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"includeCreditBalance": {
"description": "Whether to include updated credit balance information with the prebook.",
"type": "string"
},
"prebookId": {
"description": "(Required) The unique identifier of the prebook session.",
"type": "string"
}
},
"required": [
"prebookId"
],
"type": "object"
},
"name": "get_prebooks_prebookid",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch for bookings by guest ID or client reference. Perfect for displaying a guest's booking history or finding bookings by your internal reference codes.\n\n## When to Use\n\n- **Guest booking history** - Show all bookings for a specific guest\n- **Reference lookup** - Find bookings by your internal reference codes\n- **Booking management** - List bookings for administrative purposes\n- **Customer support** - Quickly find bookings for support tickets\n\n## What You Get\n\n- **Booking list** - All matching bookings with complete details\n- **Guest information** - Name, email, and contact details\n- **Stay details** - Check-in/check-out dates and hotel information\n- **Payment status** - Current payment and booking status\n- **Booking references** - Booking IDs and confirmation codes\n\n## Search Options\n\n- **By guest ID** - Find all bookings for a specific guest\n- **By client reference** - Find bookings using your internal reference codes\n- **By customTags** - Narrow results by booking labels using `customTags=KEY:VALUE,KEY2:VALUE2` (AND across keys)\n- **Optional timeout** - Set request timeout (default 4 seconds)\n\n## Quick Start\n\nProvide either `guestId` or `clientReference` (or both). Returns matching bookings with full details.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"clientReference": {
"type": "string"
},
"customTags": {
"description": "Filter by customTags. Comma-separated `KEY:VALUE` pairs (e.g. `SOURCE:GOOGLE,TIER:GOLD`); all pairs are joined with AND. Keys must match `^[A-Z0-9_-]+$`, up to 5 keys, value up to 255 characters. Value matching is case-insensitive.",
"type": "string"
},
"guestId": {
"type": "string"
},
"timeout": {
"description": "request timeout in seconds",
"type": "number"
}
},
"type": "object"
},
"name": "listBookings",
"outputSchema": null
},
{
"description": "## Overview\n\n**Hard Amendment** — Search for alternative rates at the same hotel and create ready-to-book prebook sessions for a confirmed booking. Used when the guest needs to change their check-in/check-out dates or room occupancy.\n\n## When to Use\n\n- **Date changes** — Guest needs different check-in or check-out dates\n- **Occupancy changes** — Guest needs a different number of adults or children\n- **Hard amendments** — Situations where the booking must be cancelled and re-booked with new parameters\n\n## How It Works\n\n1. The system searches for live availability at the same hotel with the new parameters.\n2. Up to `maxPrebooks` alternative rates are selected (sorted by price ascending). Defaults to 3 when omitted; capped at 10 (any larger value is silently clamped to 10).\n3. A prebook session is created for each rate.\n4. The caller receives a list of `prebookId` values ready to be used with `POST /rates/rebook`.\n\n## What You Get\n\n- **Up to `maxPrebooks` prebook sessions** — Each with a `prebookId`, final pricing, cancellation policies, and room details\n- **Price comparison** — `priceDifferencePercent` shows how each alternative compares to the **original booking's selling price** (negative = cheaper than what the guest paid, positive = more expensive)\n- **Policy change flags** — `cancellationChanged` and `boardChanged` highlight any policy differences\n\n## Completing the Amendment\n\nPass the chosen `prebookId` and the original `bookingId` as `existingBookingId` to `POST /rates/rebook`. On success, the new booking is created **and the original booking is automatically cancelled** — no separate cancellation call is needed.\n\n## Key Notes\n\n- The booking must be in **CONFIRMED** status.\n- If the original booking is non-refundable, only non-refundable alternatives are returned (unless overridden with `refundableRatesOnly`).\n- **Payment type is honoured** — only rates that support the original booking's payment type are returned. A pay-at-property booking only sees `PROPERTY_PAY` alternatives; every other booking (including pay-later, succeeded, credit_line) only sees `MAQAMI_PAY` alternatives. Pay-later eligibility additionally requires a refundable rate, which is enforced automatically when the original booking was refundable.\n- The nationality and currency of the original booking are used for the availability search.\n- If the cancellation of the original booking fails after the new booking is created, the error is logged but the new booking is still returned.\n\n## Quick Start\n\n1. Call this endpoint with the `bookingId` and new `occupancies`/dates — get back up to `maxPrebooks` `prebookId` values.\n2. Call `POST /rates/rebook` with the chosen `prebookId` and `existingBookingId` — new booking confirmed, original cancelled.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"boardType": {
"description": "Filter results by board/meal-plan type (e.g. `RO` for Room Only, `BB` for Bed & Breakfast). Leave empty to return all board types.",
"type": "string"
},
"bookingId": {
"description": "(Required) The unique identifier of the confirmed booking to amend.",
"type": "string"
},
"checkin": {
"description": "The new check-in date in YYYY-MM-DD format. Must be before `checkout`.",
"type": "string"
},
"checkout": {
"description": "The new check-out date in YYYY-MM-DD format. Must be after `checkin`.",
"type": "string"
},
"maxPrebooks": {
"description": "Maximum number of alternative prebook sessions to create. Defaults to 3 when omitted. Values above 10 are silently capped at 10; values ≤ 0 fall back to the default. The response may contain fewer entries when the hotel does not have enough distinct alternative offers.",
"type": "integer"
},
"occupancies": {
"description": "The desired room occupancies for the amended stay. One entry per room.",
"items": {
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adults for this room.",
"type": "integer"
},
"children": {
"description": "Ages of children for this room (empty array if no children).",
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"adults"
],
"type": "object"
},
"type": "array"
},
"refundableRatesOnly": {
"description": "When true, only fully refundable alternative rates are returned. Defaults to false (or true if the original booking was refundable).",
"type": "boolean"
}
},
"required": [
"bookingId",
"occupancies"
],
"type": "object"
},
"name": "post_bookings_bookingid_alternative_prebooks",
"outputSchema": null
},
{
"description": "## Overview\n\n**Beta Feature** - Generate short, AI-written \"Smart Highlight\" cards for a hotel. Each highlight is a title plus a one or two sentence description, generated directly in the requested language.\n\n**Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** per API key for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response.\n\n## When to Use\n\n- **Hotel detail pages** - Show a few compelling reasons to consider a property\n- **Partner-specific tone** - Adjust voice and emphasis per surface via `tone`, `style` and per-highlight `context`\n\n## What You Get\n\n- Exactly `count` highlights, always, in the requested order\n- `type` echoed back from the request so you can map each card to your own UI\n- `generated` indicating whether the copy is AI-generated or template fallback\n\n## Behaviour\n\nHotel facts are resolved server-side from `hotelId`; the caller never supplies them. The model sees the name, city, country, and description, plus a sample of facilities, rooms, and policies, guest sentiment when one is stored, and classification (star rating, hotel type, chain). Generated copy is grounded in those facts.\n\nIf AI generation fails, the endpoint still returns `200` with the requested number of neutral template highlights and `generated: false`. It never returns an empty array for a valid hotel.\n\nResults are cached, so repeated calls with an identical request body return identical copy.\n\n**Note:** This is a beta feature and may be subject to changes.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"count": {
"description": "Number of highlights to generate. If `highlights` is supplied, `count` must equal its length.",
"type": "integer"
},
"highlights": {
"description": "Per-highlight guidance. Omit for generic generation. When supplied, its length must equal `count` and the response preserves this order.",
"items": {
"additionalProperties": false,
"properties": {
"context": {
"description": "Free-text guidance describing what this highlight should emphasise. Treated as topic guidance only; claims not supported by the hotel's data will not be invented.",
"type": "string"
},
"type": {
"description": "Partner-defined category label, echoed back in the response.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hotelId": {
"description": "Unique ID of the hotel (MAQAMI format)",
"type": "string"
},
"language": {
"description": "Language code. Highlights are generated directly in this language.",
"type": "string"
},
"style": {
"description": "Formatting preferences such as title or description length.",
"type": "string"
},
"tone": {
"description": "Global writing guidance, e.g. `professional and inviting` or `calm and practical`.",
"type": "string"
}
},
"required": [
"hotelId",
"language"
],
"type": "object"
},
"name": "post_data_hotel_highlights",
"outputSchema": null
},
{
"description": "## Overview\n\nComplete a flight reservation by confirming a prebook and processing payment. This is the final step in the booking flow.\n\n## When to Use\n\n- **Final booking confirmation** - Convert a prebook into a confirmed booking\n- **Payment completion** - Confirm with Stripe (`TRANSACTION_ID`), bill an enabled **credit line** (`CREDIT`), pay with a **credit card** (`CREDIT_CARD` via the secure endpoint), or charge the **card stored on your account** (`ACC_CREDIT_CARD`)\n- **After service selection** - Book after optionally attaching seats or baggage via the services endpoint\n\n## What You Get\n\n- **Confirmed booking** with a unique booking ID\n- **Payment confirmation** with transaction details\n- **Full itinerary** including all segments and passenger assignments\n- **Provider confirmation** reference number\n\n## Key Features\n\n- **Idempotent**: Returns the existing booking (HTTP 200 + `data[0].message`) if one already exists for the given `prebookId`. Transient book failures are retried in place without exposing a terminal failure status. Concurrent duplicate requests while a book is in progress return HTTP 409 (`45035`).\n- **Payments**: Stripe uses `transactionId` from prebook or attach-services after SDK confirmation; credit line uses `CREDIT` with server-side eligibility checks; `CREDIT_CARD` charges the provided card immediately — send card details in `billingInfo` via `https://pci-book.MAQAMI.travel` (contact the team to enable this on your API key); `ACC_CREDIT_CARD` charges the card saved on your account immediately, with no card details in the request (in sandbox it simulates the booking without a charge)\n- **Provider confirmation**: Finalizes the reservation on the provider side\n\n## Quick Start\n\n**Required fields**: `prebookId` (from `POST /flights/prebooks`), `payment` with `method` and, for Stripe, `transactionId`\n\n**Tip**: If you used `POST /flights/prebooks/{prebookId}/services` to attach ancillary services, use the new `transactionId` from that response, not the original prebook `transactionId`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"customTags": {
"additionalProperties": {},
"description": "Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$` (uppercase letters, digits, `-`, `_`). Values are arbitrary strings up to 255 characters.",
"type": "object"
},
"metadata": {
"additionalProperties": false,
"description": "Optional. Encapsulates essential booking metadata, including IP, location, language, device details, and marketing parameters.",
"properties": {
"country": {
"description": "The country inferred from the requester's IP, aiding in regional compliance.",
"type": "string"
},
"device_id": {
"description": "A unique identifier for the user's device, useful for tracking and security.",
"type": "string"
},
"ip": {
"description": "IPv4/IPv6 address of the requester (or derived).",
"type": "string"
},
"language": {
"description": "The preferred language from the user's browser settings.",
"type": "string"
},
"platform": {
"description": "The operating system or device platform from which the request originates.",
"type": "string"
},
"user_agent": {
"description": "The browser/OS user agent string for verifying request authenticity.",
"type": "string"
},
"utm_campaign": {
"description": "An identifier for the specific marketing campaign that led to the request.",
"type": "string"
},
"utm_medium": {
"description": "The marketing medium (e.g., email, ad) through which the service was accessed.",
"type": "string"
},
"utm_source": {
"description": "The source of the traffic, such as a search engine or social network.",
"type": "string"
}
},
"type": "object"
},
"payment": {
"additionalProperties": false,
"description": "Payment for `POST /flights/bookings`: Stripe (`TRANSACTION_ID` + `transactionId`), credit line (`CREDIT`), whitelabel/CMI (`THIRD_PARTY` + `token`), direct card via the secure endpoint (`CREDIT_CARD` + `billingInfo`), or the card stored on your account (`ACC_CREDIT_CARD`).",
"properties": {
"billingInfo": {
"additionalProperties": false,
"description": "Card details for the payment. Required when `method` is `CREDIT_CARD`. Accepts any credit or debit card, including virtual credit cards. Send card details via the secure payment endpoint (`https://pci-book.MAQAMI.travel`); card number and security code are tokenized before reaching MAQAMI.",
"properties": {
"creditCardExpirationMonth": {
"description": "Card expiration month (MM).",
"type": "string"
},
"creditCardExpirationYear": {
"description": "Card expiration year (YYYY).",
"type": "string"
},
"creditCardIdentifier": {
"description": "The card security code (CVC/CVV).",
"type": "string"
},
"creditCardNumber": {
"description": "The card number.",
"type": "string"
},
"holderName": {
"description": "Cardholder name. Defaults to the first passenger's name if omitted.",
"type": "string"
}
},
"required": [
"creditCardNumber",
"creditCardIdentifier",
"creditCardExpirationMonth",
"creditCardExpirationYear"
],
"type": "object"
},
"method": {
"enum": [
"TRANSACTION_ID",
"CREDIT",
"THIRD_PARTY",
"CREDIT_CARD",
"ACC_CREDIT_CARD"
],
"type": "string"
},
"token": {
"description": "RSA-signed JWT from the whitelabel payment gateway when `method` is `THIRD_PARTY`. Required for CMI/WL checkout. The token must reference the same prebook and include the gateway transaction id.",
"type": "string"
},
"transactionId": {
"description": "Stripe payment intent transaction id when using `TRANSACTION_ID`. Omit when using `CREDIT`, `THIRD_PARTY`, `CREDIT_CARD`, or `ACC_CREDIT_CARD`.",
"type": "string"
}
},
"required": [
"method"
],
"type": "object"
},
"prebookId": {
"description": "The prebookId returned by `POST /flights/prebooks` (prebook must have completed the book step).",
"type": "string"
}
},
"required": [
"prebookId",
"payment"
],
"type": "object"
},
"name": "post_flights_bookings",
"outputSchema": null
},
{
"description": "Cancel an existing confirmed flight booking. For passenger security, you must provide the bookingId along with the passenger email address or last name.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The flight booking identifier to cancel",
"type": "string"
},
"email": {
"description": "The passenger contact email (required for verification).",
"type": "string"
},
"lastName": {
"description": "The passenger last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "post_flights_bookings_bookingid_cancellations",
"outputSchema": null
},
{
"description": "## Overview\n\nInitiate a flight booking session by reserving the offer with the provider, creating a payment intent when you use the Stripe SDK, and discovering available ancillary services — all in a single request.\n\n## When to Use\n\n- **Start the booking flow** once a user has confirmed their flight selection\n- **Collect passenger details** and initiate payment processing\n- **Discover add-ons** like seat selection and extra baggage before final confirmation\n\n## What You Get\n\n- **Prebook ID** required to complete the booking at `/flights/bookings`\n- **Payment intent** (`transactionId`, `secretKey`) when `usePaymentSdk` is true — for Stripe SDK integration\n- **Credit line snapshot** (`creditLine` in the response) when you set `includeCreditBalance: true` and your account has an enabled credit line with payment bypass\n- **Available services** (`servicesAttachable`) including seats and baggage options\n- **Booking confirmation** from the provider with reservation details\n\n## Key Features\n\n- **End-to-end prebook flow**: Verifies offer → payment setup (Stripe payment intent or credit line) → books with provider → fetches services\n- **Payment options**: `usePaymentSdk: true` uses the Stripe SDK. `usePaymentSdk: false` is allowed when your user has **payment bypass** (sandbox or whitelabel) and either an **enabled credit line** or a **whitelabel/CMI** checkout (no Stripe intent; complete payment via WL and call `/flights/bookings` with `payment.method: THIRD_PARTY` and `payment.token`)\n- **Ancillary services**: Returns attachable services (seats, baggage) that can be added before final booking\n- **Same shape as /book**: Uses `offerId` instead of `prebookId`\n\n## Quick Start\n\n**Required fields**: `offerId` (from search/verify), `contact` (name, email, phone), `passengers` (with birthday, document, and name details).\n\n**Payment**: Send `usePaymentSdk: true` for Stripe (typical). Send `usePaymentSdk: false` when paying on credit line or via whitelabel/CMI (requires payment bypass); otherwise you receive a validation error.\n\n**Tip**: Use the `servicesAttachable` in the response to offer seat selection or extra baggage before calling `/flights/bookings`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contact": {
"additionalProperties": false,
"description": "Primary contact person for the booking (receives confirmation emails)",
"properties": {
"email": {
"description": "Contact email address for booking confirmation",
"type": "string"
},
"firstName": {
"description": "Contact first name",
"type": "string"
},
"lastName": {
"description": "Contact last name",
"type": "string"
},
"middleName": {
"description": "Contact middle name (optional)",
"type": "string"
},
"phoneCountryCode": {
"description": "Phone country code without + (e.g. 1 for US, 33 for France)",
"type": "string"
},
"phoneNumber": {
"description": "Phone number without country code",
"type": "string"
}
},
"required": [
"email",
"firstName",
"lastName",
"phoneNumber"
],
"type": "object"
},
"includeCreditBalance": {
"description": "Optional flag to include credit line information in the response. When set to true, credit line details will be returned if the user has a credit line available.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Optional. Traveler metadata (IP, device, language, marketing parameters), same shape as `POST /flights/bookings` `metadata`. It is stored with the prebook and attached to the Stripe payment intent so the traveler's IP / device (rather than your backend's) is visible for fraud review. When omitted, the request IP and User-Agent are used.",
"properties": {
"country": {
"description": "The country inferred from the traveler's IP, aiding in regional compliance.",
"type": "string"
},
"device_id": {
"description": "A unique identifier for the user's device, useful for tracking and security.",
"type": "string"
},
"ip": {
"description": "IPv4/IPv6 address of the traveler (or derived).",
"type": "string"
},
"language": {
"description": "The preferred language from the user's browser settings.",
"type": "string"
},
"platform": {
"description": "The operating system or device platform from which the request originates.",
"type": "string"
},
"user_agent": {
"description": "The browser/OS user agent string for verifying request authenticity.",
"type": "string"
},
"utm_campaign": {
"description": "An identifier for the specific marketing campaign that led to the request.",
"type": "string"
},
"utm_medium": {
"description": "The marketing medium (e.g., email, ad) through which the service was accessed.",
"type": "string"
},
"utm_source": {
"description": "The source of the traffic, such as a search engine or social network.",
"type": "string"
}
},
"type": "object"
},
"offerId": {
"description": "The offerId from the search results (msgpack-encoded; unpacks to provider offerId)",
"type": "string"
},
"passengers": {
"description": "List of passengers travelling. Length must match the adults+children+infants counts from the search.",
"items": {
"additionalProperties": false,
"properties": {
"birthday": {
"description": "Date of birth (YYYY-MM-DD)",
"type": "string"
},
"documentExpiry": {
"description": "Travel document expiry date (YYYY-MM-DD)",
"type": "string"
},
"documentIssueCountry": {
"description": "ISO country code of the document issuing country",
"type": "string"
},
"documentNumber": {
"description": "Travel document number",
"type": "string"
},
"documentType": {
"description": "Type of travel document (e.g. passport, id_card)",
"type": "string"
},
"firstName": {
"description": "Passenger first name (as on travel document)",
"type": "string"
},
"gender": {
"description": "Passenger gender: M or F",
"type": "string"
},
"lastName": {
"description": "Passenger last name (as on travel document)",
"type": "string"
},
"loyaltyPrograms": {
"description": "Frequent flyer / loyalty programs for this passenger (Sabre and Travelport only; ignored for Atlas).",
"items": {
"additionalProperties": false,
"properties": {
"airlineCode": {
"description": "IATA airline code of the loyalty program (e.g. AA, BA, LH)",
"type": "string"
},
"programNumber": {
"description": "Frequent flyer number / membership ID",
"type": "string"
}
},
"required": [
"airlineCode",
"programNumber"
],
"type": "object"
},
"type": "array"
},
"middleName": {
"description": "Passenger middle name (optional)",
"type": "string"
},
"nationality": {
"description": "Passenger nationality as ISO country code",
"type": "string"
},
"passengerType": {
"description": "Passenger type: 0 = adult, 1 = child, 2 = infant",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"payment": {
"additionalProperties": false,
"description": "Payment configuration options",
"properties": {
"descriptorSuffix": {
"description": "Suffix appended to the Stripe payment descriptor (visible on customer's bank statement)",
"type": "string"
},
"paymentMethodConfiguration": {
"description": "Stripe Payment Method Configuration ID (pmc_...) controlling which payment methods Payment Element presents for this PaymentIntent.",
"type": "string"
}
},
"type": "object"
},
"travelPurpose": {
"description": "Optional purpose of the trip.",
"enum": [
"LEISURE",
"BUSINESS"
],
"type": "string"
},
"usePaymentSdk": {
"description": "If true, a Stripe payment intent is created (`transactionId`, `secretKey`). If false, payment bypass must apply and the account must use credit line or whitelabel/CMI checkout (no Stripe intent); otherwise the request is rejected.",
"type": "boolean"
},
"voucherCode": {
"description": "An optional voucher code to apply discounts to the booking. The vouchers API allows creation of these discounts",
"type": "string"
}
},
"required": [
"offerId",
"contact",
"passengers"
],
"type": "object"
},
"name": "post_flights_prebooks",
"outputSchema": null
},
{
"description": "## Overview\n\nAdd ancillary services such as seat selection or extra baggage to an existing prebook before confirming the final booking.\n\n## When to Use\n\n- **Seat selection** - Allow users to choose specific seats after prebook\n- **Extra baggage** - Let users add additional luggage allowance\n- **Price update** - Required when services change the total booking cost\n- **Voucher discount** - Optional `voucherCode` when attaching services changes the total and you need the discount reflected on the new payment intent\n\n## What You Get\n\n- **Updated prebook** with the selected services attached\n- **New payment intent** (`transactionId`, `secretKey`) reflecting the updated total price (after any voucher discount)\n- **Same response format** as `POST /flights/prebooks` for easy integration\n\n## Key Features\n\n- **Seat selection**: Assign specific seats to each passenger and segment\n- **Extra baggage**: Add checked baggage or overweight allowances\n- **Updated payment**: Creates a new Stripe payment intent when the prebook used Stripe (`usePaymentSdk: true`). For whitelabel/CMI prebooks (`used_custom_payment_keys`), no new intent is returned — re-charge via WL and submit a fresh JWT at `POST /flights/bookings`\n- **Voucher recalculation**: When a voucher applies, the discount is recomputed against the updated total (journey + ancillaries); invalid or expired vouchers return `400` (same as prebook)\n- **Modifies in place**: Updates the existing prebook record in the database\n\n## Quick Start\n\nProvide the `prebookId` in the URL path and `selectedServices` in the request body. Optionally pass `voucherCode` to apply a discount. Use the **new** `transactionId` from this response (not the original prebook `transactionId`) when confirming payment with Stripe and when calling `POST /flights/bookings`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"prebookId": {
"description": "The prebook ID (must have provider_booking_id from initial prebook)",
"type": "string"
},
"selectedServices": {
"description": "Services to attach (from servicesAttachable.groups in prebook response)",
"items": {
"additionalProperties": false,
"description": "An ancillary service selected by a passenger (seat, baggage, etc.)",
"properties": {
"passengerIndex": {
"description": "Zero-based index of the passenger this service is for (matches position in passengers array)",
"type": "integer"
},
"quantity": {
"description": "Number of units of this service to attach",
"type": "integer"
},
"serviceId": {
"description": "Service identifier from servicesAttachable.groups[].services[].serviceId",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"voucherCode": {
"description": "An optional voucher code to apply discounts to the booking. The vouchers API allows creation of these discounts",
"type": "string"
}
},
"required": [
"prebookId",
"selectedServices"
],
"type": "object"
},
"name": "post_flights_prebooks_prebookid_services",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch for available flights with real-time pricing from multiple providers. The itinerary **must** be sent as a non-empty `legs` array. Each leg follows the provider **SearchLeg** shape: required `origin`, `destination`, and `date` (YYYY-MM-DD); optional `direction` (`OUTBOUND` or `INBOUND`); optional per-leg `filters` that override global `filters` for that leg only.\n\n**Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only.\n\n## When to Use\n\n- **Listings** — live prices for search results UI\n- **One-way, round-trip, or multi-city** — one leg per segment, in order\n- **Filtering** — cabin class, stops, price, refundability, times (globally or per leg)\n- **Streaming** — incremental provider results over SSE\n\n## What You Get\n\n- Offers from multiple providers\n- Itineraries with segments, layovers, and durations\n- Price breakdown (fares, taxes, fees) and baggage hints\n\n## Key Features\n\n- Multi-provider aggregation in one request\n- **SSE:** send header `Accept: text/event-stream` on `POST /flights/rates`, or `POST /flights/rates/stream` with the same JSON body\n- Global `filters`, `sort`\n\n## Quick Start\n\n**Required:** `legs` (at least one object with `origin`, `destination`, `date`), `adults` (≥ 1), `currency`\n\n**Round-trip:** two legs (e.g. outbound then return with `direction` `OUTBOUND` / `INBOUND`). **One-way:** one leg.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adults (12+)",
"type": "integer"
},
"cabinClass": {
"description": "Cabin class (provider SearchFilters codes only). Same enum as filters.cabinClass.",
"enum": [
"ECONOMY",
"PREMIUM_ECONOMY",
"BUSINESS",
"FIRST"
],
"type": "string"
},
"children": {
"description": "Number of children (2-11)",
"type": "integer"
},
"childrenAges": {
"description": "Age of each child (2–11 inclusive, per IATA). Length must equal children count. Optional — omit if ages are not relevant.",
"items": {
"type": "integer"
},
"type": "array"
},
"country": {
"description": "Optional ISO 3166-1 alpha-2 country code for point of sale",
"type": "string"
},
"currency": {
"description": "ISO 4217 currency code",
"type": "string"
},
"filters": {
"additionalProperties": false,
"description": "Optional filters to refine search results",
"properties": {
"arrivalTimeBefore": {
"description": "Filter journeys arriving before this time (HH:MM, 24h)",
"type": "string"
},
"cabinClass": {
"enum": [
"ECONOMY",
"PREMIUM_ECONOMY",
"BUSINESS",
"FIRST",
"Economy",
"Business",
"First"
],
"type": "string"
},
"cabinClassMatch": {
"enum": [
"exactly",
"at_least"
],
"type": "string"
},
"changeableOnly": {
"description": "When true, only show offers with changeable (modifiable) fares",
"type": "boolean"
},
"departureTimeBefore": {
"description": "Filter journeys departing before this time (HH:MM, 24h)",
"type": "string"
},
"excludeConnectionAirports": {
"description": "Exclude layovers at these airports (e.g. IST, DOH)",
"items": {
"type": "string"
},
"type": "array"
},
"excludeOvernight": {
"description": "Exclude red-eye flights and overnight layovers",
"type": "boolean"
},
"flightNumbers": {
"description": "Filter by flight numbers (e.g. SK500, AF123)",
"items": {
"type": "string"
},
"type": "array"
},
"flightNumbersMatch": {
"enum": [
"any",
"all"
],
"type": "string"
},
"includesCarryOnBag": {
"description": "Only show offers with carry-on included",
"type": "boolean"
},
"includesCheckedBag": {
"description": "Only show offers with checked bag included",
"type": "boolean"
},
"legDurations": {
"description": "Per-leg max duration constraints. Each entry limits one direction (OUTBOUND or INBOUND) independently.",
"items": {
"additionalProperties": false,
"properties": {
"direction": {
"enum": [
"OUTBOUND",
"INBOUND"
],
"type": "string"
},
"maxMinutes": {
"description": "Maximum leg duration in minutes (inclusive)",
"type": "integer"
}
},
"required": [
"direction",
"maxMinutes"
],
"type": "object"
},
"type": "array"
},
"maxDuration": {
"description": "Maximum total journey duration in minutes (inclusive). Journeys exceeding this duration are excluded.",
"type": "integer"
},
"maxPrice": {
"description": "Maximum total price (offer total, in search currency)",
"type": "number"
},
"maxStops": {
"description": "Maximum number of stops: -1 or omit = any, 0 = genuinely non-stop, 1 = 1 or fewer, 2 = 2 or fewer. Stops include both connections between segments and en-route technical stops inside a segment (segments[].stopCount), so a single flight number with a technical landing is excluded by maxStops: 0.",
"type": "integer"
},
"minPrice": {
"description": "Minimum total price (offer total, in search currency)",
"type": "number"
},
"refundableOnly": {
"description": "When true, only show offers with refundable fares",
"type": "boolean"
},
"showCheapestOfferOnly": {
"description": "Return only cheapest offer per journey",
"type": "boolean"
}
},
"type": "object"
},
"infantAges": {
"description": "Age of each infant (under 2, per IATA). Length must equal infants count. Optional — omit if ages are not relevant.",
"items": {
"type": "integer"
},
"type": "array"
},
"infants": {
"description": "Number of infants (<2)",
"type": "integer"
},
"legs": {
"description": "Ordered itinerary legs (provider SearchLeg). One-way: one entry. Round-trip: outbound then inbound. Multi-city / open-jaw: additional legs in travel order.",
"items": {
"additionalProperties": false,
"properties": {
"date": {
"description": "Departure date for this leg (YYYY-MM-DD)",
"type": "string"
},
"destination": {
"description": "Destination airport or city IATA code for this leg",
"type": "string"
},
"direction": {
"enum": [
"OUTBOUND",
"INBOUND"
],
"type": "string"
},
"filters": {
"additionalProperties": false,
"description": "Optional per-leg filters overriding global `filters` for this leg",
"properties": {
"arrivalTimeAfter": {
"description": "Arrival after this local time (HH:MM, 24h)",
"type": "string"
},
"arrivalTimeBefore": {
"description": "Arrival before this local time (HH:MM, 24h)",
"type": "string"
},
"departureTimeAfter": {
"description": "Departure after this local time (HH:MM, 24h)",
"type": "string"
},
"departureTimeBefore": {
"description": "Departure before this local time (HH:MM, 24h)",
"type": "string"
},
"excludeConnectionAirports": {
"items": {
"type": "string"
},
"type": "array"
},
"excludeOvernight": {
"type": "boolean"
},
"flightNumbers": {
"items": {
"type": "string"
},
"type": "array"
},
"flightNumbersMatch": {
"enum": [
"any",
"all"
],
"type": "string"
},
"maxDuration": {
"description": "Max leg duration in minutes",
"type": "integer"
},
"maxStops": {
"description": "Max stops for this leg. Counts connections between segments and en-route technical stops inside a segment (segments[].stopCount); 0 = genuinely non-stop.",
"type": "integer"
}
},
"type": "object"
},
"origin": {
"description": "Origin airport or city IATA code for this leg",
"type": "string"
}
},
"required": [
"origin",
"destination",
"date"
],
"type": "object"
},
"type": "array"
},
"margin": {
"additionalProperties": false,
"description": "Optional per-request markup overrides. Each property is a percentage that replaces your account-level flight markup for that category on this search only; categories you omit keep their configured markup. Set at least one property. Only honoured when flight margin editing is enabled for your account; ignored otherwise. `rateSearch` is applied to the fare prices returned by this search; `seats`, `bags` and `penalties` are attached to the returned offerIds and applied when the offer is verified, prebooked and booked.",
"properties": {
"bags": {
"description": "Markup percentage for baggage ancillaries and journey baggage prices.",
"type": "number"
},
"penalties": {
"description": "Markup percentage applied to the displayed airline change / refund fees (`terms.changeFee`, `terms.refundFee`).",
"type": "number"
},
"rateSearch": {
"description": "Fare markup percentage (journey total and per-passenger prices). Takes precedence over any airline/route overrides configured for your account.",
"type": "number"
},
"seats": {
"description": "Markup percentage for seat ancillaries.",
"type": "number"
}
},
"type": "object"
},
"sort": {
"additionalProperties": false,
"description": "Sort options for results",
"properties": {
"sortBy": {
"enum": [
"price",
"duration",
"departure",
"arrival",
"stops"
],
"type": "string"
},
"sortOrder": {
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
"type": "object"
}
},
"required": [
"legs",
"adults",
"currency"
],
"type": "object"
},
"name": "post_flights_rates",
"outputSchema": null
},
{
"description": "## Overview\n\nConfirm a flight offer is still available and retrieve the latest pricing before proceeding to booking. Always verify before prebooking to avoid price discrepancies.\n\n## When to Use\n\n- **Pre-booking validation** - Confirm offer availability after user selects a flight\n- **Price confirmation** - Show users the guaranteed price before they enter payment details\n- **Fare rule retrieval** - Get the latest cancellation and change policies\n\n## What You Get\n\n- **Verified pricing** with up-to-date fare breakdown\n- **`changes`** (when present) — cabin/fare flags, human-readable `messages`, and **`pricing`** (`old` / `new` full OfferPricing) instead of deprecated scalar currency/prices\n- **Journey `pricing`** — `original` (provider/PCC) and `display` (customer) price breakdown per provider FlattenedJourney\n- **Fare family details** including name and included amenities\n- **Baggage policy** for each passenger type and segment\n- **Booking terms** including cancellation and change fee rules\n\n## Key Features\n\n- **Real-time price check**: Confirms current availability and price with the provider\n- **Updated baggage info**: Returns the latest baggage allowances at time of verification\n- **Fare rules**: Includes cancellation and change fee policies before commitment\n\n## Quick Start\n\nProvide the `offerId` from `/flights/rates` search results. Use the verified offer data to populate a booking summary page before proceeding to `/flights/prebooks`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"offerId": {
"description": "The offerId from the search results",
"type": "string"
}
},
"required": [
"offerId"
],
"type": "object"
},
"name": "post_flights_verify",
"outputSchema": null
},
{
"description": "## Overview\n\nGet the cheapest available rate for each hotel in your list. Perfect for displaying price comparisons without loading full rate details.\n\n## When to Use\n\n- **Show price ranges** on hotel listing pages\n- **Quick price comparisons** across multiple hotels\n- **Optimize performance** when you only need the lowest price, not all rate options\n- **Build price filters** or sorting by price\n\n## What You Get\n\n- **Minimum rate per hotel** - the cheapest available room option\n- **Basic rate information** - price, currency, and availability\n- **Fast response** - optimized for quick price lookups\n\n## Key Features\n\n- **Lightweight** - Returns only the minimum rate, not all options\n- **Same parameters** as the main rates endpoint for consistency\n- **Perfect for listings** - Ideal when displaying multiple hotels where users just need to see starting prices\n\n## Quick Start\n\nProvide a list of hotel IDs, dates, and guest occupancy. The endpoint returns the cheapest rate available for each hotel.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"checkin": {
"description": "Check in date in YYYY-MM-DD (ISO 8601) format",
"type": "string"
},
"checkout": {
"description": "Check out date in YYYY-MM-DD (ISO 8601) format",
"type": "string"
},
"currency": {
"description": "Booking currency",
"type": "string"
},
"guestNationality": {
"description": "Guest nationality (ISO 2-code)",
"type": "string"
},
"hotelIds": {
"description": "List of hotel IDs",
"items": {
"type": "string"
},
"type": "array"
},
"occupancies": {
"items": {
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adults in each selected room",
"type": "integer"
},
"children": {
"description": "The ages of children of each selected room",
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"adults"
],
"type": "object"
},
"type": "array"
},
"timeout": {
"description": "Request timeout in seconds",
"type": "number"
}
},
"required": [
"hotelIds",
"occupancies",
"checkin",
"checkout",
"currency",
"guestNationality"
],
"type": "object"
},
"name": "post_hotels_min_rates",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch for hotel rates and availability across multiple hotels. This is your primary endpoint for finding bookable hotel rooms with real-time pricing.\n\n## When to Use\n\n- **Display hotel listings** with prices on your search results page\n- **Show detailed rate options** for specific hotels users are viewing\n- **Support multi-room bookings** for families or groups\n- **Filter hotels** by location, amenities, ratings, or AI-powered semantic search\n\n## What You Get\n\n- **Real-time rates** with availability and pricing\n- **Multiple room options** per hotel, sorted by price\n- **Complete booking details** including cancellation policies, meal plans, and room types\n- **Hotel information** (name, photos, address, ratings) when searching by filters\n\n## Key Features\n\n- **Multiple search methods**: Search by hotel IDs, city/country, coordinates, Place ID, IATA code, or natural language (AI search)\n- **Flexible filtering**: Filter by star rating, facilities, hotel chains, accessibility, and more\n- **Multi-room support**: Book multiple rooms with different guest configurations in one request\n- **Performance optimized**: Default limit of 200 hotels (expandable to 5,000), recommended timeout of 6-12 seconds\n- **Price consistency**: Optional `sessionId` ensures rates stay consistent across listing and detail searches within a user session (accounts with price consistency enabled)\n\n## Quick Start\n\n**Required fields**: `checkin`, `checkout`, `currency`, `guestNationality`, `occupancies`, plus one location method (hotel IDs, city/country, coordinates, Place ID, or IATA code)\n\n**Tip**: When searching by filters (like `aiSearch` or `cityName`), hotel data is automatically included. For direct hotel ID searches, set `includeHotelData=true` to include hotel names and photos.\n\n**Price consistency**: Generate a unique `sessionId` per user search session and include it on every rates request in that session, using the same `checkin`, and `checkout`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"advancedAccessibilityOnly": {
"description": "If true, only hotels with advanced accessibility features will be returned.",
"type": "boolean"
},
"aiSearch": {
"description": "AI-powered hotel search based on a natural language query. Uses semantic search to find hotels matching the query intent. Examples: 'Romantic getaway with Italian vibes in London near the London Eye', 'hotels near Paris'. This is a valid main query.",
"type": "string"
},
"amenityFilterLogic": {
"description": "Legacy logic applied to roomAmenities. 'AND': room must have all specified amenities. 'OR': room must have at least one specified amenity. Ignored when roomAmenitiesFilter is provided.",
"enum": [
"AND",
"OR"
],
"type": "string"
},
"bedTypes": {
"description": "Filter results by bed types extracted from room names. Only rates from rooms matching the specified bed types will be returned. Example values: 'double', 'twin', 'king', 'queen', 'single'.",
"items": {
"type": "string"
},
"type": "array"
},
"boardType": {
"description": "Filter results by board type(s). Can be a single value (e.g., 'BI') or comma-separated values (e.g., 'BI,HB') for OR logic. Example values: RO (Room Only), BI (Breakfast Included), HB (Half Board), FB (Full Board), AI (All Inclusive), DI (Dinner Included), LI (Lunch Included), BDI (Breakfast and Dinner Included), BLI (Breakfast and Lunch Included), LDI (Lunch and Dinner Included).",
"type": "string"
},
"chainIds": {
"description": "An array of hotel chain IDs to filter the search results. This is a filter on top of the main query.",
"items": {
"type": "number"
},
"type": "array"
},
"checkin": {
"description": "The check-in date in YYYY-MM-DD format (ISO 8601).",
"type": "string"
},
"checkout": {
"description": "The check-out date in YYYY-MM-DD format (ISO 8601).",
"type": "string"
},
"cityName": {
"description": "The name of the city to search for hotels in. Pairs with countryCode to do a country/city search.",
"type": "string"
},
"countryCode": {
"description": "The country code in ISO 2-letter format (e.g., 'SG' for Singapore). Instead of using hotel IDs, you can search by country/city. This is a valid main query.",
"type": "string"
},
"currency": {
"description": "The currency in which the prices will be displayed.",
"type": "string"
},
"facilities": {
"description": "An array of facility IDs. Results will include hotels with at least one of these facilities by default. This is a filter on top of the main query.",
"items": {
"type": "number"
},
"type": "array"
},
"feed": {
"description": "Which feed to use when searching for rates. This applies only to accounts with multiple feeds enabled",
"type": "string"
},
"guestNationality": {
"description": "The guest's nationality in ISO 2-letter country code format.",
"type": "string"
},
"hotelIds": {
"description": "An array of hotel IDs to search for availability and pricing. These are usually pulled from https://docs.MAQAMI.travel/reference/get_data-hotels.",
"items": {
"type": "string"
},
"type": "array"
},
"hotelName": {
"description": "A case-insensitive search for a hotel's name (e.g., 'Hilton').",
"type": "string"
},
"hotelTypeIds": {
"description": "An array of hotel type IDs to filter the search results. This is a filter on top of the main query.",
"items": {
"type": "number"
},
"type": "array"
},
"iataCode": {
"description": "The IATA code of the search location, typically an airport code. Instead of using hotel IDs, you can search by IATA code. This is a valid main query.",
"type": "string"
},
"includeHotelData": {
"description": "If `true`, includes hotel data (name, main photo, address, rating) in the response even when searching by direct hotel IDs. By default, hotel data is only included when searching by filters (e.g., using `aiSearch`, `countryCode`, `cityName`, etc.). Setting this to `true` enables hotel data inclusion for all search types.",
"type": "boolean"
},
"latitude": {
"description": "The latitude coordinate for location-based hotel searches. Instead of using hotel IDs, you can search by lat/long and a radius around that spot. This is a valid main query.",
"type": "number"
},
"limit": {
"description": "The maximum number of results to return. Defaults to 200, max allowed is 5000.",
"type": "integer"
},
"longitude": {
"description": "The longitude coordinate for location-based hotel searches. Pairs with latitude to do a lat/long search.",
"type": "number"
},
"loyaltyProgram": {
"description": "Loyalty program identifier used to request loyalty-eligible rates from supported suppliers. When set, rates that support the program may return member pricing and benefits.",
"type": "string"
},
"loyaltyProgramDetails": {
"description": "Loyalty membership details forwarded to supported suppliers to unlock member rates and benefits. Provide one entry per loyalty program membership.",
"items": {
"additionalProperties": false,
"properties": {
"membershipId": {
"description": "The guest's membership ID for the loyalty program.",
"type": "string"
},
"programId": {
"description": "The loyalty program identifier (e.g., 'HH' for Hilton Honors).",
"type": "string"
}
},
"required": [
"membershipId",
"programId"
],
"type": "object"
},
"type": "array"
},
"margin": {
"description": "Override the markup percentage for this specific request. When provided, this value takes precedence over your account-level margin setting, allowing you to dynamically adjust pricing based on your business logic, customer segments, or other factors. Specified as a percentage number (e.g., `10` for 10% commission).",
"type": "number"
},
"maxRatesPerHotel": {
"description": "The number of room rates to return per hotel, sorted by price (cheapest first). Set to 1 to just get the cheapest rate for each hotel, this is helpful for listing pages. Try increasing this if you are missing rate types, and be aware that the cap is applied before room mapping.",
"type": "integer"
},
"minRating": {
"description": "The minimum rating (on a scale of 0-5) required for hotels in search results. This is a filter on top of the main query.",
"type": "number"
},
"minReviewsCount": {
"description": "The minimum number of reviews a hotel must have to be included in results. This is a filter on top of the main query.",
"type": "integer"
},
"occupancies": {
"description": "An array of objects specifying the number of guests per room. Required.",
"items": {
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adults in each selected room",
"type": "integer"
},
"children": {
"description": "The ages of children of each selected room",
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"adults"
],
"type": "object"
},
"type": "array"
},
"offset": {
"description": "The number of results to skip for pagination. This paginates the passed hotels not the results returned so the actual returned results will vary.",
"type": "integer"
},
"placeId": {
"description": "The unique Place ID of the search location. Instead of using hotel IDs, pass a Place ID to get all the hotels in the specified region. This is a valid main query.",
"type": "string"
},
"radius": {
"description": "The search radius in meters for location-based searches. Pairs with latitude to do a lat/long search.",
"type": "integer"
},
"refundableRatesOnly": {
"description": "If true, only refundable rates (RFN) will be included in the response.",
"type": "boolean"
},
"roomAmenities": {
"description": "Legacy room-level amenity filter. Only rates from rooms that match the specified amenities will be returned. Use amenityFilterLogic to control flat AND/OR behavior. If roomAmenitiesFilter is provided, it takes precedence over this field.",
"items": {
"type": "number"
},
"type": "array"
},
"roomAmenitiesFilter": {
"description": "Grouped room-level amenity filter. Use '-' for OR within a group and ',' for AND across groups. Example: '1-2,3-4' means (1 OR 2) AND (3 OR 4). If provided, this field takes precedence over roomAmenities and amenityFilterLogic.",
"type": "string"
},
"roomMapping": {
"description": "Enable room mapping to retrieve the mappedRoomId for each room. This allows you to link a rate to its specific room by combining it with hotel details, providing access to room images and additional information",
"type": "boolean"
},
"sessionId": {
"description": "Optional client-generated session identifier that ensures price consistency for the user's search session. When your account has price consistency enabled, pass the same `sessionId` with the same `checkin` and `checkout` across related requests in that session. Has no effect when price consistency is not enabled for your account.",
"type": "string"
},
"sort": {
"description": "Sorting criteria for the results. Multiple criteria can be provided, processed in order. The default sorting is by top picks (weighted by search popularity, review quality, and content completeness). Use 'revenue' to sort by historical booking value and monetary performance.",
"items": {
"additionalProperties": false,
"properties": {
"direction": {
"enum": [
"ascending",
"descending"
],
"type": "string"
},
"field": {
"enum": [
"top_picks",
"price",
"revenue"
],
"type": "string"
}
},
"required": [
"field"
],
"type": "object"
},
"type": "array"
},
"starRating": {
"description": "An array of hotel star ratings to include. Ratings are rounded to the nearest half-star (e.g., [3.5, 4.0, 4.5, 5.0]). This is a filter on top of the main query.",
"items": {
"type": "number"
},
"type": "array"
},
"stream": {
"description": "If true, enables streaming mode where response data is sent incrementally instead of as a single payload.",
"type": "boolean"
},
"strictFacilityFiltering": {
"description": "If enabled, only hotels with all specified facilities will be returned.",
"type": "boolean"
},
"timeout": {
"description": "The maximum time in seconds before the request times out. This is when the live request for rates will cut off responses; it will take a few more ms to return the value.",
"type": "integer"
},
"zip": {
"description": "The zip code of the search location. This is a filter on top of the main query.",
"type": "string"
}
},
"required": [
"occupancies",
"currency",
"guestNationality",
"checkin",
"checkout"
],
"type": "object"
},
"name": "post_hotels_rates",
"outputSchema": null
},
{
"description": "## Overview\n\n**Step 2 of 2** in the booking flow. Complete the booking by providing guest information and payment details. This confirms the reservation and creates the final booking.\n\n## When to Use\n\n- **After prebook** - Call this after creating a prebook session\n- **Payment processing** - Submit payment information to confirm booking\n- **Booking confirmation** - Finalize the reservation\n\n## What You Get\n\n- **Booking ID** - Unique identifier for the confirmed booking\n- **Hotel confirmation code** - Reference code from the hotel\n- **Complete booking details** - Dates, pricing, room information\n- **Cancellation policies** - Terms for cancelling the booking\n- **Guest information** - Confirmed guest details\n\n## Payment Methods\n\n- **ACC_CREDIT_CARD** - Direct credit card payment. In sandbox mode, this can be used to simulate a booking without getting charged.\n- **TRANSACTION** - Use when using Payment SDK (provide `transactionId`)\n- **WALLET** - Wallet payment method\n- **CREDIT** - Use account credit balance\n- **CREDIT_CARD** - Credit card payment via secure endpoint. Accepts any credit or debit card, including virtual credit cards. Send card details via `https://pci-book.MAQAMI.travel` using the `billingInfo` object. Contact the team to enable this on your API key.\n\n## Testing\n\nWhen testing sandbox bookings, simply use the `ACC_CREDIT_CARD` payment method. This allows you to simulate a booking without getting charged.\n\n## Required Information\n\n- **Prebook ID** - From the prebook step\n- **Guest details** - First name, last name, and email\n- **Payment information** - Payment method and details\n\n## Quick Start\n\nProvide the `prebookId`, guest information (firstName, lastName, email), and payment details. Returns confirmed booking with booking ID and confirmation code.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"clientReference": {
"description": "An optional client-defined reference ID acts as an idempotency key to prevent duplicate bookings. If a booking already exists with the same client reference, the API will return a 4005 error.",
"type": "string"
},
"customTags": {
"additionalProperties": {},
"description": "Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$` (uppercase letters, digits, `-`, `_`). Values are arbitrary strings up to 255 characters. These labels are returned on booking responses and can be used to filter the list endpoints via the `customTags=KEY:VALUE,KEY2:VALUE2` query parameter.",
"type": "object"
},
"guestPayment": {
"additionalProperties": false,
"description": "The payment method used for the transaction. This determines where the money for the booking comes from. Recommended to be added when you are merchant of record to improve the fraud detection system.",
"properties": {
"address": {
"additionalProperties": false,
"description": " Billing address details of the payee",
"properties": {
"address": {
"description": "Street address",
"type": "string"
},
"city": {
"description": "City of the billing address",
"type": "string"
},
"country": {
"description": "Country of the billing address",
"type": "string"
},
"postal_code": {
"description": "Postal or ZIP code",
"type": "string"
}
},
"type": "object"
},
"last_4_digits": {
"description": "Last 4 digits of the credit card used for payment",
"type": "string"
},
"method": {
"description": "Payment method used (e.g., ACC_CREDIT_CARD, CREDIT_CARD, WALLET).",
"type": "string"
},
"payee_first_name": {
"description": "First name of the person making the payment",
"type": "string"
},
"payee_last_name": {
"description": "Last name of the person making the payment",
"type": "string"
},
"phone": {
"description": "Contact number associated with the payment",
"type": "string"
}
},
"required": [
"phone",
"method",
"payee_last_name",
"payee_first_name",
"last_4_digits"
],
"type": "object"
},
"guests": {
"description": "This represents a list of all individuals included in the hotel reservation",
"items": {
"additionalProperties": false,
"properties": {
"email": {
"description": "The email of the primary guest staying in the assigned room",
"type": "string"
},
"firstName": {
"description": "The first name of the primary guest staying in this assigned room",
"type": "string"
},
"lastName": {
"description": "The last name of the primary guest staying in the assigned room",
"type": "string"
},
"occupancyNumber": {
"description": "An array where each object represents the primary guest assigned to a specific booked room. There is a 1:1 mapping between guests and rooms, meaning each guest object corresponds to a single room in the booking. (Doc for more details: https://docs.MAQAMI.travel/docs/adding-guests-durring-the-booking-step)",
"type": "integer"
},
"phone": {
"description": "The guest's contact number for verification and hotel communication",
"type": "string"
},
"remarks": {
"description": "Special requests or remarks for the guest's stay (not guaranteed)",
"type": "string"
}
},
"required": [
"occupancyNumber",
"firstName",
"lastName",
"email"
],
"type": "object"
},
"type": "array"
},
"holder": {
"additionalProperties": false,
"description": "Information on the person responsible for making the payment. This may not necessarily be the traveler",
"properties": {
"email": {
"description": "The email address of the payer",
"type": "string"
},
"firstName": {
"description": "The first name of the payer",
"type": "string"
},
"lastName": {
"description": "The last name of the payer",
"type": "string"
},
"phone": {
"description": "The phone number of the payer, if available",
"type": "string"
}
},
"required": [
"firstName",
"lastName",
"email",
"phone"
],
"type": "object"
},
"metadata": {
"additionalProperties": false,
"description": "Encapsulates essential metadata for fraud detection and compliance, including IP, location, language, device details, and marketing parameters.",
"properties": {
"country": {
"description": "The country inferred from the requester's IP, aiding in regional compliance.",
"type": "string"
},
"device_id": {
"description": "A unique identifier for the user's device, useful for tracking and security.",
"type": "string"
},
"ip": {
"description": " ip String (or derived) IPv4/IPv6 of the requester",
"type": "string"
},
"language": {
"description": "The preferred language from the user's browser settings.",
"type": "string"
},
"platform": {
"description": "The operating system or device platform from which the request originates.",
"type": "string"
},
"user_agent": {
"description": "The browser/OS user agent string for verifying request authenticity.",
"type": "string"
},
"utm_campaign": {
"description": "An identifier for the specific marketing campaign that led to the request.",
"type": "string"
},
"utm_medium": {
"description": "The marketing medium (e.g., email, ad) through which the service was accessed.",
"type": "string"
},
"utm_source": {
"description": "The source of the traffic, such as a search engine or social network.",
"type": "string"
}
},
"type": "object"
},
"payment": {
"description": "Specifies the payment method for completing the booking"
},
"prebookId": {
"description": "This identifier from the pre-booking step is used to confirm a booking rate",
"type": "string"
},
"timeout": {
"type": "integer"
}
},
"required": [
"prebookId",
"holder",
"guests"
],
"type": "object"
},
"name": "post_rates_book",
"outputSchema": null
},
{
"description": "## Overview\n\n**Step 1 of 2** in the booking flow. Create a prebook session to check the availability of a rate and get final pricing before payment. This `prebookId` needed to complete the booking.\n\n## When to Use\n\n- **Before payment** - Always call this before completing a booking\n- **Rate confirmation** - Verify final pricing and availability\n- **Session creation** - Generate a checkout session for your payment flow\n\n## What You Get\n\n- **Prebook ID** - Required for the next step (completing the booking)\n- **Final pricing** - Confirmed rates with all fees and taxes\n- **Terms and conditions** - Cancellation policies and booking rules\n- **Room details** - Complete information about the selected rooms\n\n## Key Features\n\n- **Live availability check** - Verifies the rate is available before you collect payment\n- **Payment SDK support** - Set `usePaymentSdk=true` to use client-side payment forms\n- **Reusable** - PrebookId can be used for multiple bookings if needed\n\n## Quick Start\n\nProvide the `offerId` from your hotel rates search and set `usePaymentSdk` (true/false). Returns a `prebookId` to use in the next step.\n\n**Next Step**: Use the `prebookId` with `/rates/book` to complete the booking.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"addons": {
"description": "A list of additional services or extras that can be added to the booking. For example, adding an Uber voucher or an esim card. The final booking amount is the sum of the offer's total price and the cost of any addons. Each addon's price is added individually to reflect all extras in the billed total. ",
"items": {
"additionalProperties": false,
"properties": {
"addon": {
"description": "The type of addon service (e.g., uber, esimply).",
"type": "string"
},
"addonDetails": {
"additionalProperties": false,
"properties": {
"destination_code": {
"description": " Short code representing the destination or country (e.g., ES for Spain)",
"type": "string"
},
"end_date": {
"description": "The end date for the add-on service (YYYY-MM-DD format)",
"type": "string"
},
"package_id": {
"description": "Unique identifier of the addon package",
"type": "integer"
},
"start_date": {
"description": "The start date for the add-on service (YYYY-MM-DD format)",
"type": "string"
}
},
"type": "object"
},
"currency": {
"description": "The currency in which the addon service is charged",
"type": "string"
},
"value": {
"description": "The monetary cost of the addon service",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"bedTypeIds": {
"description": "An optional array of bed type IDs to specify preferred bed configurations for the rooms being booked. The availability of specific bed types depends on the hotel's inventory.",
"items": {
"type": "integer"
},
"type": "array"
},
"includeCreditBalance": {
"description": "Optional flag to include credit line information in the response. When set to true, credit line details will be returned if the user has a credit line available.",
"type": "boolean"
},
"offerId": {
"description": "The unique identifier of the selected offer from the search results.",
"type": "string"
},
"payment": {
"additionalProperties": false,
"description": "Optional payment configuration when usePaymentSdk is true",
"properties": {
"descriptorSuffix": {
"description": "Suffix appended to the Stripe payment descriptor (visible on customer's bank statement)",
"type": "string"
},
"gateway": {
"description": "Payment gateway when using partner Stripe keys. Only STRIPE is supported.",
"type": "string"
},
"paymentMethodConfiguration": {
"description": "Stripe Payment Method Configuration ID (pmc_...) controlling which payment methods Payment Element presents. Must exist on the Stripe account that owns the PaymentIntent (MAQAMI or partner when useOwnSecretKey is true).",
"type": "string"
},
"useOwnSecretKey": {
"description": "When true, create the PaymentIntent on the partner's Stripe account (requires configured Stripe keys).",
"type": "boolean"
}
},
"type": "object"
},
"timeout": {
"type": "integer"
},
"usePaymentSdk": {
"description": "Specifies whether the fields needed to call the payment processing SDK are returned. Set to true if using the SDK for payment processing.",
"type": "boolean"
},
"voucherCode": {
"description": "An optional voucher code to apply discounts to the booking. The vouchers API allows creation of these discounts",
"type": "string"
}
},
"required": [
"offerId",
"usePaymentSdk"
],
"type": "object"
},
"name": "post_rates_prebook",
"outputSchema": null
},
{
"description": "## Overview\n\n**Step 2 of 2** in the **hard amendment** flow. Use a `prebookId` produced by `POST /bookings/{bookingId}/alternative-prebooks` to create the replacement booking. On success, the new booking is created **and the original booking is automatically cancelled** — you do **not** need to call the cancel endpoint.\n\n## When to Use\n\n- **After alternative-prebooks** — Once the guest has chosen one of the alternative prebooks returned by `POST /bookings/{bookingId}/alternative-prebooks`.\n- **Date or occupancy changes** — The guest needs different check-in/check-out dates or a different number of adults/children at the same hotel.\n- **Hard amendments only** — For simple guest-name updates use `PUT /bookings/{bookingId}/amend` instead.\n\n## How It Works\n\n1. The provided `prebookId` is validated against the booking referenced by `existingBookingId` (it must have been produced by an `alternative-prebooks` call for that booking).\n2. The new booking is created with the supplier using the alternative rate.\n3. The original booking is then automatically cancelled. If the cancellation fails after the new booking is confirmed, the error is logged but the new booking is still returned — contact support to reconcile.\n\n## Payment\n\n- **Pay-at-property bookings are not supported.** Bookings paid at the property (`PROPERTY_PAY`) cannot be rebooked through this endpoint.\n- No payment is collected on this endpoint. The `payment.method` value is ignored — the request body must still include a `payment` object to satisfy the schema, but the server forces the method to `NONE` internally. Any price delta between the original and new rate is settled out of band.\n\n## Refundable vs Non-refundable Originals\n\n- **Refundable original** — Returns `200 OK` with the new booking, and the original is cancelled immediately.\n- **Non-refundable original** — Returns `202 Accepted` with a booking amendment record. The request is queued for the MAQAMI operations team to handle manually (the original booking may incur cancellation fees).\n\n## Required Information\n\n- **prebookId** — A prebook session returned by `POST /bookings/{bookingId}/alternative-prebooks`.\n- **existingBookingId** — The `bookingId` of the original confirmed booking being replaced. Must match the `bookingId` that produced the prebook.\n- **holder** and **guests** — Same structure as `POST /rates/book`. If `holder` fields are empty they are copied from the original booking.\n\n## Quick Start\n\n1. Call `POST /bookings/{bookingId}/alternative-prebooks` and pick one of the returned `prebookId` values.\n2. Call this endpoint with that `prebookId`, the original `bookingId` as `existingBookingId`, and guest information.\n3. On success, the new booking is confirmed and the original is cancelled — no further calls are needed.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"clientReference": {
"description": "An optional client-defined reference ID. Acts as an idempotency key to prevent duplicate rebooks. If a booking already exists with the same client reference, the API will return a 4005 error.",
"type": "string"
},
"customTags": {
"additionalProperties": {},
"description": "Optional bag of up to 5 user-defined key/value labels persisted with the booking. Keys must match `^[A-Z0-9_-]+$` and values are strings up to 255 characters. See `POST /rates/book` for the full description.",
"type": "object"
},
"existingBookingId": {
"description": "The `bookingId` of the confirmed booking being replaced. The original booking is cancelled automatically when the new booking is confirmed.",
"type": "string"
},
"guests": {
"description": "List of guests for the new booking. There is a 1:1 mapping between guests and rooms (one guest entry per `occupancyNumber`).",
"items": {
"additionalProperties": false,
"properties": {
"email": {
"description": "Guest email.",
"type": "string"
},
"firstName": {
"description": "Guest first name.",
"type": "string"
},
"lastName": {
"description": "Guest last name.",
"type": "string"
},
"occupancyNumber": {
"description": "Which occupancy/room this guest belongs to. Must match an occupancy on the prebook.",
"type": "integer"
},
"phone": {
"description": "Guest phone number.",
"type": "string"
},
"remarks": {
"description": "Optional remarks for this guest (not guaranteed).",
"type": "string"
}
},
"required": [
"occupancyNumber",
"firstName",
"lastName",
"email"
],
"type": "object"
},
"type": "array"
},
"holder": {
"additionalProperties": false,
"description": "Information on the person responsible for the booking. Any field left empty is populated from the original booking's holder.",
"properties": {
"email": {
"description": "Email of the holder. Defaults to the original booking's holder email when empty.",
"type": "string"
},
"firstName": {
"description": "First name of the holder. Defaults to the original booking's holder first name when empty.",
"type": "string"
},
"lastName": {
"description": "Last name of the holder. Defaults to the original booking's holder last name when empty.",
"type": "string"
},
"phone": {
"description": "Phone number of the holder.",
"type": "string"
}
},
"type": "object"
},
"payment": {
"additionalProperties": false,
"description": "Required by the schema but ignored. The server forces the payment method to `NONE` for rebooks — no charge is taken on this endpoint. Send `{\"method\": \"NONE\"}` to be explicit.",
"properties": {
"method": {
"enum": [
"NONE"
],
"type": "string"
}
},
"required": [
"method"
],
"type": "object"
},
"prebookId": {
"description": "A prebook session returned by `POST /bookings/{bookingId}/alternative-prebooks`. Must reference the same booking as `existingBookingId`.",
"type": "string"
},
"timeout": {
"description": "Optional request timeout in seconds.",
"type": "integer"
},
"trackingId": {
"description": "Optional tracking ID for analytics or partner attribution.",
"type": "string"
}
},
"required": [
"prebookId",
"existingBookingId",
"holder",
"guests",
"payment"
],
"type": "object"
},
"name": "post_rates_rebook",
"outputSchema": null
},
{
"description": "## Overview\n\nCreate a temporary hold on the selected tour slot and a Stripe PaymentIntent for checkout.\n\n## When to Use\n\n- **Checkout start** — After the user picks option, slot, and participants from booking-options\n- **Payment setup** — Obtain `transactionId` and `secretKey` for Stripe SDK confirmation\n- **Hold window** — Reserve inventory for ~10 minutes before book\n\n## What You Get\n\n- **Checkout context** — `tourId`, `optionId`, `dateTime`, `language`, `participants`, and pricing echoed back\n- **Provider refs** — `cartId`, `experienceBookingId`, `providerBookingId`, `status`, `reservationExpiresAt`\n- **Stripe fields** — `transactionId`, `secretKey`, `paymentTypes: [\"TRANSACTION_ID\"]`\n\n## Quick Start\n\nPOST the same `selection` used for display pricing from booking-options with `usePaymentSdk: true`. Confirm payment with Stripe, then call `POST /experiences/bookings`.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"clientReferenceId": {
"description": "Partner reference echoed in prebook response and stored on the checkout session.",
"type": "string"
},
"currency": {
"description": "ISO 4217 currency code used for validate and downstream book cart.",
"type": "string"
},
"language": {
"description": "ISO language code used for validate and downstream book cart.",
"type": "string"
},
"payment": {
"additionalProperties": false,
"description": "Optional Stripe metadata (e.g. statement descriptor suffix).",
"properties": {
"descriptorSuffix": {
"type": "string"
}
},
"type": "object"
},
"selection": {
"additionalProperties": false,
"properties": {
"dateTime": {
"description": "Chosen slot start time from booking-options (`slots[].dateTime`).",
"format": "date-time",
"type": "string"
},
"optionId": {
"description": "Chosen tour option from booking-options.",
"type": "integer"
},
"participants": {
"items": {
"additionalProperties": false,
"properties": {
"numberOfParticipants": {
"description": "Count of participants in this category.",
"type": "integer"
},
"ticketCategory": {
"description": "Semantic participant key from availability/booking-options (e.g. `adult`, `child`).",
"type": "string"
}
},
"required": [
"ticketCategory",
"numberOfParticipants"
],
"type": "object"
},
"type": "array"
},
"price": {
"additionalProperties": false,
"properties": {
"amount": {
"description": "Partner-facing sell from booking-options (`slots[].pricing.totals.net`, equiv. `priceSummary.netPrice` after markup). Not provider retail.",
"type": "number"
},
"currency": {
"description": "ISO 4217 currency code for the slot price.",
"type": "string"
}
},
"required": [
"amount",
"currency"
],
"type": "object"
},
"questions": {
"additionalProperties": false,
"description": "Provider-neutral canonical answers for bookingQuestionSchema.",
"properties": {
"answers": {
"items": {
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "Canonical field ID from `bookingQuestionSchema`.",
"type": "string"
},
"value": {
"description": "Answer value. Type depends on the question: string for text/select, integer for date components, object for grouped fields like pickup_location."
}
},
"required": [
"fieldId"
],
"type": "object"
},
"type": "array"
},
"participantAnswers": {
"items": {
"additionalProperties": false,
"properties": {
"answers": {
"items": {
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "Canonical field ID from `bookingQuestionSchema`.",
"type": "string"
},
"value": {
"description": "Answer value. Type depends on the question: string for text/select, integer for date components, object for grouped fields like pickup_location."
}
},
"required": [
"fieldId"
],
"type": "object"
},
"type": "array"
},
"participantIndex": {
"type": "integer"
}
},
"required": [
"participantIndex",
"answers"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"required": [
"optionId",
"dateTime",
"price",
"participants"
],
"type": "object"
},
"usePaymentSdk": {
"description": "Phase 1 requires `true` to create a Stripe PaymentIntent.",
"type": "boolean"
}
},
"required": [
"selection",
"language",
"currency",
"usePaymentSdk"
],
"type": "object"
},
"name": "prebookExperienceTour",
"outputSchema": null
},
{
"description": "## Overview\n\nCreates a pending post-booking extra-charge batch for an existing flight booking and returns an opaque `chargesId`. For Stripe-paid bookings, also creates a PaymentIntent (`transactionId` + `secretKey`) when `usePaymentSdk` is true.\n\n## Access\n\nRequires Flights API access. Post-booking extra charges are not enabled by default — contact the MAQAMI support team to request access.\n\n## When to Use\n\n- Attach fees after confirmation (seat change, baggage, admin adjustment)\n- Obtain a Stripe client secret so the customer can confirm payment before `POST .../extra-charges/charges`\n\n## What You Get\n\n- **`chargesId`** — Opaque token required by `/extra-charges/charges` (do not re-send charge lines)\n- **`paymentTypes`** — Locked to the booking's original payment (`TRANSACTION_ID` or `CREDIT`)\n- **`transactionId` / `secretKey`** — Present for Stripe bookings when `usePaymentSdk` is true\n- Existing extras totals plus pending batch totals\n\n## Constraints\n\n- Booking status must be `CONFIRMED` or `PENDING_CONFIRMATION`\n- All lines in one request must share the same currency\n- Payment method on `/charges` must match the original booking payment",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "Flight booking identifier",
"type": "string"
},
"charges": {
"description": "Charge lines to attach. All lines must use the booking sellingCurrency.",
"items": {
"additionalProperties": false,
"description": "One pending post-booking extra charge line",
"properties": {
"amount": {
"description": "Positive charge amount",
"type": "number"
},
"currency": {
"description": "ISO 4217 currency code",
"type": "string"
},
"description": {
"description": "Human-readable fee label",
"type": "string"
}
},
"required": [
"description",
"currency",
"amount"
],
"type": "object"
},
"type": "array"
},
"usePaymentSdk": {
"description": "Required true for Stripe bookings so a PaymentIntent is created. Ignored for CREDIT bookings.",
"type": "boolean"
}
},
"required": [
"bookingId",
"charges"
],
"type": "object"
},
"name": "prechargeFlightExtraCharges",
"outputSchema": null
},
{
"description": "Cancel an existing confirmed hotel reservation. For traveler security and to prevent unauthorized cancellations, you must provide the bookingId along with the guest email address or last name used during booking.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bookingId": {
"description": "The unique booking identifier to cancel",
"type": "string"
},
"email": {
"description": "The guest email address used during booking (required for verification).",
"type": "string"
},
"lastName": {
"description": "The guest last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "put_bookings_bookingid",
"outputSchema": null
},
{
"description": "Amend an existing confirmed booking (dates, rooms, or guests). For traveler security, you must provide the bookingId along with the guest email address or last name used during booking.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": true,
"properties": {
"bookingId": {
"description": "The unique booking identifier to amend",
"type": "string"
},
"email": {
"description": "The guest email address used during booking (required for verification).",
"type": "string"
},
"lastName": {
"description": "The guest last name (optional alternative for verification).",
"type": "string"
}
},
"required": [
"bookingId",
"email"
],
"type": "object"
},
"name": "put_bookings_bookingid_amend",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch available tours and activities with localized content and prices in your chosen currency.\n\n## When to Use\n\n- **Search results** - Populate a tours listing or map view\n- **Destination pages** - Show activities available in a city or region\n- **Category browsing** - Filter tours by type, duration, or rating\n\n## What You Get\n\n- **Tour listings** - Titles, descriptions, images, and ratings\n- **Localized content** - Names and descriptions in the requested language\n- **Prices** - Amounts in the requested currency\n\n## Quick Start\n\nProvide required `language` and `currency` query parameters. Returns a paginated list of matching tours.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "searchExperienceTours",
"outputSchema": null
},
{
"description": "## Overview\n\nSearch the cheapest fare for each departure (and, on round-trips, return) date combination across a grid of nearby dates — `±flexDays` around the dates in your request. Accepts the same `legs`-based body as `POST /flights/rates` plus optional `flexDays` (1–3, default 3).\n\n**Supported:** one-way (1 leg) or round-trip (2 legs) only. Multi-city (3+ legs) is not supported.\n\n**Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only.\n\n## Access\n\nRequires Flights API access and matrix enablement on your account. Matrix search is not enabled by default — contact the MAQAMI support team to request access.\n\n## When to Use\n\n- **Flexible-date calendars** — price heatmap when the traveller can shift dates\n- **Cheap-date discovery** — find the lowest fare in a ±N day window before a full `/flights/rates` search\n- **Round-trip date pairing** — compare outbound × return combinations on one grid\n- **Progressive UI** — stream cells over SSE as each underlying search completes\n\n## What You Get\n\n- **`cells`** — one entry per valid date combination, sorted by `(outboundOffset, returnOffset)`\n- **`cheapest`** — globally lowest-priced cell (null when nothing was priced)\n- **`currency`** — currency of the global cheapest cell\n- **`baseOutboundDate`** / **`baseReturnDate`** — the originally requested dates\n- **`flexDays`**, **`roundTrip`** — grid metadata\n- Per-cell **`price`**, **`currency`**, date offsets, and whether the underlying search was **`cached`** or **`success`**\n- **Margined prices** — cell `price`, `cheapest`, and `currency` include the authenticated user's rate-search margin (same as `/flights/rates`)\n\n## Key Features\n\n- Probes `±flexDays` (1–3) around requested departure and return dates\n- Each underlying date pair uses normal provider caching — a later `POST /flights/rates` for a matrix date is served from warm cache\n- **SSE:** send header `Accept: text/event-stream` for incremental events: `matrix-start` (grid skeleton), `matrix-chunk` (one priced cell), `matrix-complete` (full sorted grid + cheapest)\n- Same global `filters`, `sort`, and `options` as `/flights/rates` where applicable\n\n## Quick Start\n\n**Required:** `legs` (1 leg for one-way or 2 for round-trip, each with `origin`, `destination`, `date`), `adults` (≥ 1), `currency`\n\n**Optional:** `flexDays` (1–3, default 3), `country`, passenger counts, `filters`, `sort`\n\n**Round-trip:** two legs — outbound then return with optional `direction` `OUTBOUND` / `INBOUND`. **One-way:** one leg.\n\nAfter choosing a date pair from the matrix, call `POST /flights/rates` with `legs` set to those dates for full offer details.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"adults": {
"description": "Number of adult passengers (≥ 1).",
"type": "integer"
},
"children": {
"description": "Number of child passengers (ages 2-11).",
"type": "integer"
},
"country": {
"description": "ISO country code for point of sale",
"type": "string"
},
"currency": {
"description": "ISO 4217 currency for point of sale and displayed prices.",
"type": "string"
},
"flexDays": {
"description": "Days before/after requested dates to probe",
"type": "integer"
},
"infants": {
"description": "Number of infant passengers (under 2).",
"type": "integer"
},
"legs": {
"description": "One leg (one-way) or two legs (round-trip). Multi-city is not supported.",
"items": {
"additionalProperties": false,
"properties": {
"date": {
"description": "Departure date for this leg (YYYY-MM-DD).",
"type": "string"
},
"destination": {
"description": "Destination airport or city IATA code for this leg.",
"type": "string"
},
"direction": {
"enum": [
"OUTBOUND",
"INBOUND"
],
"type": "string"
},
"origin": {
"description": "Origin airport or city IATA code for this leg.",
"type": "string"
}
},
"required": [
"origin",
"destination",
"date"
],
"type": "object"
},
"type": "array"
},
"margin": {
"additionalProperties": false,
"description": "Optional per-request markup override. Only `rateSearch` affects the matrix (cell prices are fares); other categories are accepted for parity with `/flights/rates` but have no effect here. Only honoured when flight margin editing is enabled for your account; ignored otherwise.",
"properties": {
"rateSearch": {
"description": "Fare markup percentage applied to matrix cell prices instead of your account-level flight markup.",
"type": "number"
}
},
"type": "object"
}
},
"required": [
"legs",
"adults",
"currency"
],
"type": "object"
},
"name": "searchFlightsMatrix",
"outputSchema": null
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:63d374d34314723495dc0fc25615e0e8188fc67ccfd9ce7d135cac42b2c3cbe6 | sha256sum