Flights

The flights domain wraps four provider adapters (Amadeus, Duffel, Dohop, Darwin) behind a normalized surface. Partners run their own provider search and submit the offer struct to Movmo as the booking entry point. The offer lifecycle is consistent across providers.

Common patterns

Booking flow starts at POST /v1/flights/providers/{provider}/offers — accepts a provider-native offer struct, returns a Movmo offer_id. API-key-only, so it can fire before the user authenticates.
idempotency_key required on POST .../bookings. Replay the same key on retry; Movmo deduplicates.
Ownership enforced on booking GET. Read via /v1/users/{userid}/bookings/....
Pricing is a separate step for Amadeus only (POST .../offers/{offer_id}/pricing); Duffel, Darwin, and Dohop integrate pricing into the booking step. Check getProviderCapabilities at runtime to be safe.
Seat maps are capability-gated by supports_seat_selection.

REST endpoints

Provider catalog and offer lifecycle (selected — see the spec for the full list):

Operation	Path
`listProviders`	`GET /v1/flights/providers`
`getProviderCapabilities`	`GET /v1/flights/providers/{provider}/capabilities`
`createProviderOffer`	`POST /v1/flights/providers/{provider}/offers`
`getProviderOffer`	`GET /v1/flights/providers/{provider}/offers/{offer_id}`
`priceProviderOffer`	`POST /v1/flights/providers/{provider}/offers/{offer_id}/pricing`
`saveOfferPassengers`	`POST .../offers/{offer_id}/passengers`
`updateOfferPassenger`	`PUT .../offers/{offer_id}/passengers/{passenger_id}`
`getOfferSeatMaps`	`GET .../offers/{offer_id}/seat-maps`
`createProviderBooking`	`POST /v1/flights/providers/{provider}/bookings`
`retryProviderBooking`	`POST /v1/flights/providers/{provider}/bookings/retry`
`getProviderBooking`	`GET /v1/flights/providers/{provider}/bookings/{booking_id}`
`cancelProviderBooking`	`DELETE /v1/flights/providers/{provider}/bookings/{booking_id}`

User-bookings sub-resource:

Operation	Path
`listUserBookings`	`GET /v1/users/{userid}/bookings`
`getUserBooking`	`GET /v1/users/{userid}/bookings/{bookingid}`
`getUserBookingPassengers`	`GET /v1/users/{userid}/bookings/{bookingid}/passengers`
`getUserBookingOffer`	`GET /v1/users/{userid}/bookings/{bookingid}/offer`

Full schemas in the OpenAPI spec under tags: [Flights].

MCP tools

Model Context Protocol (MCP) wrappers for this domain:

Tool	Maps to
`search_flights`	Darwin search proxy
`create_offer`	Darwin hold + `POST /v1/flights/providers/darwin/offers`
`get_offer_details`	`GET /v1/flights/providers/{provider}/offers/{offer_id}`
`get_seat_map`	Capability check + `GET .../offers/{offer_id}/seat-maps`
`update_passenger`	`PUT .../offers/{offer_id}/passengers/{passenger_id}`
`create_booking`	Internal user/offer/payment lookup + `POST .../bookings`
`get_booking`	`GET /v1/flights/providers/{provider}/bookings/{booking_id}`

search_flights and create_offer invoke Darwin only. For other providers via MCP, drive your own search, submit the offer to REST createProviderOffer, then continue with get_offer_details, update_passenger, and create_booking.

Watch out for

The duplicate /v1/flights/users/{userid}/bookings* path is deprecated and omitted from the partner surface. Always read user bookings from /v1/users/{userid}/bookings.
PUT /v1/flights/providers/{provider}/bookings/{booking_id} is a stub in the codebase and intentionally absent from the spec. Use cancel-and-rebook.
The /v1/darwin/* and Dohop air-shopping proxies are internal.