MustSeen Bridge Engine API
The official API documentation for the MustSeen Execution Layer. We transform unstructured travel plans into validated, bookable realities.
/v1/ingest
>Parse, Enrich & Validate a Travel Plan (Synchronous)
This endpoint takes an unstructured text-based travel plan, processes it through the entire Parse-Enrich-Validate pipeline, and returns the complete, validated ExecutableTrip object in a single, synchronous request. The connection is held open until processing is complete or a timeout is reached.
Request Body
{
"type": "object",
"properties": {
"planText": {
"type": "string",
"example": "A 2-day trip to Paris for 2 people in October. Flight from Berlin on Friday, return Sunday. We want a hotel near the Eiffel Tower."
}
}
}Responses
Successful validation. The full ExecutableTrip object is returned.
{
"$ref": "#/components/schemas/ExecutableTrip"
}{
"name": "3 day trip to Paris from Berlin",
"raw_text": "A 3 day trip to Paris from Berlin, flight and hotel.",
"segments": [
{
"id": "seg_1",
"type": "FLIGHT",
"original_text": "flight to Paris from Berlin",
"parsed_data": {
"origin": {
"name": "Berlin",
"iata": "BER"
},
"destination": {
"name": "Paris",
"iata": "PAR"
},
"departure_date": "2025-07-25",
"passengers": 1
},
"validation": {
"status": "not_found",
"validated_at": "2025-07-23T16:53:19.000Z",
"results": [],
"error_message": null
}
},
{
"id": "seg_2",
"type": "HOTEL",
"original_text": "hotel in Paris",
"parsed_data": {
"destination": {
"name": "Paris",
"iata": "PAR"
},
"departure_date": "2025-07-25",
"return_date": "2025-07-28",
"duration_days": 3,
"passengers": 1
},
"validation": {
"status": "success",
"validated_at": "2025-07-23T16:53:21.137Z",
"results": [
{
"option_id": 12893159,
"price_eur": 436.74,
"provider": "Booking.com",
"metadata": {
"name": "Charming apartment - 1BR-4P- Gare de l'Est"
}
}
]
}
},
{
"id": "seg_3",
"type": "FLIGHT",
"original_text": "flight back to Berlin",
"parsed_data": {
"origin": {
"name": "Paris",
"iata": "PAR"
},
"destination": {
"name": "Berlin",
"iata": "BER"
},
"departure_date": "2025-07-28",
"passengers": 1
},
"validation": {
"status": "not_found",
"validated_at": "2025-07-23T16:53:19.017Z",
"results": [],
"error_message": null
}
}
],
"status": "validated"
}Bad Request - Invalid input data.
Unauthorized - Invalid or missing API Key.
Rate Limit Exceeded.
Service Unavailable - External provider might be down.
/v1/passengers
>Create Passenger Information
Create secure passenger information for booking. This endpoint handles PII data with encryption and Row-Level Security.
Request Body
{
"$ref": "#/components/schemas/PassengerCreate"
}Responses
Passenger created successfully
{
"$ref": "#/components/schemas/PassengerResponse"
}Invalid passenger data
{
"$ref": "#/components/schemas/Error"
}Authentication required
/v1/booking/execute
>Execute Booking - Phase 1
First phase of two-step booking process. Confirms flight prices with Amadeus and creates Stripe payment intent. Returns client_secret for payment processing.
Request Body
{
"$ref": "#/components/schemas/BookingExecuteRequest"
}Responses
Booking execution successful - payment intent created
{
"$ref": "#/components/schemas/BookingExecuteResponse"
}Invalid request or price mismatch
{
"$ref": "#/components/schemas/Error"
}Authentication required
Price has changed since lock - refresh required
/v1/booking/confirm
>Confirm Booking - Phase 2
Second phase of two-step booking process. Verifies payment status and creates actual flight booking with Amadeus. Must be called after successful payment.
Request Body
{
"$ref": "#/components/schemas/BookingConfirmRequest"
}Responses
Booking confirmed successfully
{
"$ref": "#/components/schemas/BookingConfirmResponse"
}Invalid session or payment not confirmed
Booking session not found
Booking failed - automatic refund initiated
{
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"refundId": {
"type": "string",
"description": "Stripe refund ID for automatic refund"
}
}
}
]
}