{
  "components": {
    "securitySchemes": {
      "x402PaymentSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "Base64-encoded x402 payment payload."
      },
      "customerSupportCode": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Customer-Support-Code",
        "description": "Per-intent support code returned at intent creation (for example `BRIJ-K7MQ-T9RV`). Authorizes reading the airline order and filing a refund request. Not a payment credential."
      },
      "brijSponsoredPreview": {
        "type": "apiKey",
        "in": "header",
        "name": "X-BRIJ-SPONSORED-SIGNATURE",
        "description": "BRIJ gateway Ed25519 signature for sponsored preview calls. The signature covers version, timestamp, wallet address, method, host, path, and request body hash."
      },
      "authorSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token from POST /recipes/session, scoped to recipe authorship."
      }
    },
    "parameters": {
      "IntentID": {
        "name": "intent_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "The intent id returned when the intent was created."
      }
    },
    "schemas": {
      "StatusResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "ok",
              "ready",
              "not_ready"
            ]
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": [
          "origin_iata",
          "destination_iata",
          "depart_date"
        ],
        "properties": {
          "origin_iata": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "example": "MAD",
            "description": "Departure airport or city IATA code, 3 letters (e.g. MAD)."
          },
          "destination_iata": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "example": "LIS",
            "description": "Arrival airport or city IATA code, 3 letters (e.g. LIS)."
          },
          "depart_date": {
            "type": "string",
            "format": "date",
            "example": "2026-06-10",
            "description": "Outbound date, YYYY-MM-DD."
          },
          "return_date": {
            "type": "string",
            "format": "date",
            "description": "Optional. Adds the inbound slice (destination back to origin on this date). Round-trip offers cover both directions and are booked in ONE /air/book — the escrow amount is the round-trip total.",
            "example": "2026-08-22"
          },
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9,
            "description": "Adult passengers, 1 to 9 (the airline maximum per booking). The offer is priced for this many travellers, and /air/book must later supply exactly this many passengers."
          },
          "cabin_class": {
            "type": "string",
            "enum": [
              "economy",
              "premium_economy",
              "business",
              "first"
            ],
            "description": "Optional, defaults to economy."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "description": "Optional. Cap the number of offers returned; 0 or absent returns every match. Offers are sorted per `sort` (cheapest first by default), so a limit keeps the best ones under that order. ONE EXCEPTION, and it is why the array can hold limit+1 rows: when the cut would have dropped the cheapest NONSTOP, that offer is appended as the last row, so a page never hides that a direct exists even from a caller that reads no other field. It is appended, never inserted at its price rank — the first `limit` rows are still the `limit` best under your sort, and offers[0] is still the cheapest. `highlights` names it too."
          },
          "cheapest_per_itinerary": {
            "type": "boolean",
            "description": "Optional. Return only the cheapest fare of each physical itinerary (comparison_key); the folded fares stay visible in each offer's fare_options (offer_id, brand, price, refundable, changeable, checked bags), so refundability questions are answerable from the grouped data itself. Recommended for LLM-driven agents together with limit."
          },
          "sort": {
            "type": "string",
            "enum": [
              "price",
              "duration",
              "departure",
              "emissions",
              "nonstop_first"
            ],
            "description": "Ordering, ascending only. Default price. duration = fastest first, departure = earliest local departure first, emissions = lowest CO2 first (unknown values sort last). nonstop_first = every nonstop itinerary (price-ascending) before any connection — with a limit, directs survive the cut."
          },
          "max_stops": {
            "type": "integer",
            "minimum": 0,
            "nullable": true,
            "description": "Maximum plane changes PER DIRECTION: 0 keeps directs only (a round trip qualifies only if both legs are direct). Absent = any. Technical stops without a plane change do not count."
          },
          "departure_after": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Outbound departs at or after this time, LOCAL to the departure airport, HH:MM.",
            "example": "12:00"
          },
          "departure_before": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Outbound departs at or before this time, local HH:MM. Combine with departure_after for a window: afternoon = after 12:00, before 18:00.",
            "example": "18:00"
          },
          "max_price": {
            "type": "string",
            "description": "Decimal cap on total_amount in the offer currency, e.g. \"250.00\".",
            "example": "250.00"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "search"
        ],
        "properties": {
          "search": {
            "$ref": "#/components/schemas/SearchResult"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "request_id",
          "offers"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "example": "orq_0000B5xGbA4yXTVomvGU2G"
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferSummary"
            }
          },
          "search_id": {
            "type": "string",
            "description": "Capability token for POST /air/search-updates. The search answers fast with the quick fulfillers' offers; slower tiers keep adding offers for a couple of minutes, and this token reads them as they land. Unguessable; expires ~5 minutes after the search. Treat it like a secret.",
            "example": "srch_2f7c1de09ab34455ee01aa8b90c2d711"
          },
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "enriching"
            ],
            "description": "\"complete\" when every fulfiller tier has finished quoting; \"enriching\" while slower tiers are still adding offers — poll /air/search-updates to receive them."
          },
          "fulfillers": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "complete",
                "running"
              ]
            },
            "description": "Per-tier quoting state, e.g. {\"fastbooking\": \"complete\"}."
          },
          "poll_after_ms": {
            "type": "integer",
            "description": "Suggested delay before the next /air/search-updates poll. Absent when the search is complete."
          },
          "next": {
            "type": "string",
            "description": "Present while status is enriching: what to do, in words — keep polling /air/search-updates until complete before choosing. Absent when complete."
          },
          "matched_count": {
            "type": "integer",
            "description": "How many offers survived the filters and grouping BEFORE the limit cut — what a full listing would hold."
          },
          "highlights": {
            "$ref": "#/components/schemas/SearchHighlights"
          }
        }
      },
      "SearchHighlights": {
        "type": "object",
        "description": "The three offers an agent asks about first — cheapest, fastest, cheapest nonstop — each taken from EVERYTHING that matched, before the limit cut. A page of the 15 cheapest is only honest if it says what it left out: on a long-haul route every one of the 15 cheapest can be a connection while a direct exists at a higher price. Read cheapest_nonstop before concluding a route has no direct flight. A field is absent when no offer qualifies (no nonstop on the route, or none within max_stops / the time window).",
        "properties": {
          "cheapest": {
            "$ref": "#/components/schemas/SearchHighlight"
          },
          "fastest": {
            "$ref": "#/components/schemas/SearchHighlight"
          },
          "cheapest_nonstop": {
            "$ref": "#/components/schemas/SearchHighlight"
          }
        }
      },
      "SearchHighlight": {
        "type": "object",
        "required": [
          "offer_id",
          "total_amount_decimal",
          "total_currency",
          "duration",
          "stops",
          "departing_at"
        ],
        "properties": {
          "offer_id": {
            "type": "string",
            "description": "Bookable like any other offer (POST /air/offer-details, then /air/intents), whether or not it appears in offers.",
            "example": "fastbooking:off_0000B9nB2EOrQ54IWMWb3F"
          },
          "total_amount_decimal": {
            "type": "string",
            "description": "The price a buyer pays for this offer — what POST /air/intents asks as expected_escrow_amount.",
            "example": "1300.97"
          },
          "total_currency": {
            "type": "string",
            "example": "USD"
          },
          "duration": {
            "type": "string",
            "description": "Whole journey, every direction summed, ISO 8601.",
            "example": "PT23H30M"
          },
          "stops": {
            "type": "integer",
            "description": "Total plane changes across every direction; 0 = nonstop both ways."
          },
          "carrier_name": {
            "type": "string",
            "example": "British Airways"
          },
          "departing_at": {
            "type": "string",
            "description": "Local departure of the first segment.",
            "example": "2026-11-12T18:00:00"
          }
        }
      },
      "OfferSummary": {
        "type": "object",
        "required": [
          "id",
          "owner_name",
          "origin_iata",
          "destination_iata",
          "departing_at",
          "arriving_at",
          "origin_time_zone",
          "destination_time_zone",
          "stops",
          "technical_stops",
          "duration",
          "comparison_key",
          "fare_brand_name",
          "cabin_class",
          "checked_bags_included",
          "carry_on_bags_included",
          "conditions",
          "slices",
          "total_emissions_kg",
          "identity_documents_required",
          "total_amount",
          "total_amount_decimal",
          "total_currency",
          "requires_instant_payment"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "fastbooking:off_0000B5xGbDG4ifAoeDTtG9"
          },
          "owner_name": {
            "type": "string",
            "example": "Air Europa"
          },
          "origin_iata": {
            "type": "string",
            "description": "Start of the whole journey (first leg's origin).",
            "example": "MAD"
          },
          "destination_iata": {
            "type": "string",
            "description": "End of the whole journey (last leg's destination), NOT the first connection point.",
            "example": "LIS"
          },
          "departing_at": {
            "type": "string",
            "description": "Journey departure, airport-local time with no UTC offset.",
            "example": "2026-08-02T14:42:00"
          },
          "arriving_at": {
            "type": "string",
            "description": "FINAL arrival at the journey destination, airport-local time with no UTC offset.",
            "example": "2026-08-02T21:10:00"
          },
          "origin_time_zone": {
            "type": "string",
            "description": "IANA timezone of the journey origin.",
            "example": "America/New_York"
          },
          "destination_time_zone": {
            "type": "string",
            "description": "IANA timezone of the journey destination.",
            "example": "America/Los_Angeles"
          },
          "stops": {
            "type": "integer",
            "description": "Number of connections. 0 means a direct flight.",
            "example": 1
          },
          "technical_stops": {
            "type": "integer",
            "description": "Refuelling-type stops across all legs, without plane change. Truly non-stop = stops 0 and technical_stops 0."
          },
          "segments": {
            "type": "array",
            "description": "Every leg of the itinerary, in order.",
            "items": {
              "$ref": "#/components/schemas/OfferSegment"
            }
          },
          "duration": {
            "type": "string",
            "description": "Whole-journey duration, ISO 8601.",
            "example": "PT7H28M"
          },
          "comparison_key": {
            "type": "string",
            "description": "Identifies the physical itinerary: offers with the SAME comparison_key are the same flights at different fares or sellers. Group by it to deduplicate results (a search commonly returns 100+ offers for a few dozen itineraries).",
            "example": "cmp_abc123"
          },
          "fare_brand_name": {
            "type": "string",
            "description": "Airline's name for this fare (e.g. \"Basic\", \"Flexible Balearic\"). The SAME flight is listed once per fare and per seller: use this plus conditions, baggage and owner_name to tell same-flight offers apart. Empty when the airline did not name the fare.",
            "example": "Flexible Balearic"
          },
          "cabin_class": {
            "type": "string",
            "description": "Normalized cabin: economy, premium_economy, business, first. Empty when unknown.",
            "example": "economy"
          },
          "cabin_class_marketing_name": {
            "type": "string",
            "description": "The airline's own name for the cabin.",
            "example": "ECONOMY"
          },
          "checked_bags_included": {
            "type": "integer",
            "nullable": true,
            "description": "Checked bags included for the WHOLE journey (minimum across legs). null = the airline did not say — do not assume 0."
          },
          "carry_on_bags_included": {
            "type": "integer",
            "nullable": true,
            "description": "Carry-on bags included for the whole journey. null = unknown."
          },
          "conditions": {
            "nullable": true,
            "description": "Change/refund permissions for this fare; null when the airline disclosed nothing.",
            "allOf": [
              {
                "$ref": "#/components/schemas/FareConditions"
              }
            ]
          },
          "fare_options_count": {
            "type": "integer",
            "description": "Present only on cheapest_per_itinerary searches: how many fares of this same itinerary were collapsed into this cheapest one."
          },
          "fare_options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferFareOption"
            },
            "description": "Present on cheapest_per_itinerary searches: EVERY fare of this itinerary (this offer included), cheapest first. The grouped view is lossless on price, brand, refund/change conditions and checked bags — never claim such a fare does not exist without reading this list."
          },
          "slices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferSlice"
            },
            "description": "Each direction of the journey: one entry for a one-way, two for a round trip (outbound then inbound). The journey-level fields above describe the OUTBOUND for compatibility; slices is the canonical and only complete view for round trips. comparison_key joins all directions, so two round trips sharing an outbound but not a return stay distinct."
          },
          "total_emissions_kg": {
            "type": "string",
            "description": "Estimated CO2 for the journey, decimal kilograms. Empty when the provider does not report it. Varies several-fold between offers on the same route.",
            "example": "21"
          },
          "identity_documents_required": {
            "type": "boolean",
            "description": "true = this fare demands passenger identity documents, which this API cannot collect: POST /air/intents refuses such offers with 409 identity_documents_not_supported. Filter them out before choosing."
          },
          "supported_loyalty_programmes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IATA codes of airline loyalty programmes this offer can credit miles to (e.g. BA, AF, UA). Empty when none or unknown."
          },
          "base_amount_decimal": {
            "type": "string",
            "description": "Fare before tax; total = base + tax.",
            "example": "65.00"
          },
          "base_currency": {
            "type": "string",
            "example": "USD"
          },
          "tax_amount_decimal": {
            "type": "string",
            "example": "24.50"
          },
          "tax_currency": {
            "type": "string",
            "example": "USD"
          },
          "total_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Atomic amount used by the API for money comparisons.",
            "example": 67600000
          },
          "total_amount_decimal": {
            "type": "string",
            "example": "67.60"
          },
          "total_currency": {
            "type": "string",
            "example": "USD"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "requires_instant_payment": {
            "type": "boolean"
          },
          "price_guarantee_expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "payment_required_by": {
            "type": "string",
            "format": "date-time"
          },
          "passenger_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CreateIntentRequest": {
        "type": "object",
        "required": [
          "funding_wallet",
          "offer_id"
        ],
        "properties": {
          "funding_wallet": {
            "type": "string",
            "description": "Solana wallet expected to fund the escrow."
          },
          "refund_wallet": {
            "type": "string",
            "description": "Optional Solana wallet for refunds. Defaults to funding_wallet."
          },
          "offer_id": {
            "type": "string",
            "description": "The offer to book, sent back EXACTLY as received from POST /air/search or POST /air/offer-details — never reassembled by hand.",
            "example": "fastbooking:off_0000000000000000000000"
          },
          "promo_code": {
            "type": "string",
            "description": "Optional discount code the user gave you (e.g. from a community or campaign). Send it exactly as the user wrote it; case does not matter. Waives the BRIJ service fee on flights and hotels. Checked BEFORE any payment: an unusable code refuses the intent, free, with promo_invalid (404), promo_expired (410), promo_exhausted (409, no seats left) or already_member (409, this wallet already redeemed a code) — tell the user and retry without it. When it applies, the answer carries intent.promo_code and a fee_amount of 0. The code is redeemed for the funding wallet once that wallet funds the escrow; after that every booking from the wallet is fee-free until the benefit ends, with no code to resend.",
            "example": "EXAMPLECODE"
          },
          "referrer": {
            "type": "string",
            "description": "Optional affiliate code (see POST /affiliates). Not a discount: it credits the referrer a share of the platform fee. Unknown or self-referring codes are silently ignored."
          }
        }
      },
      "IntentResponse": {
        "type": "object",
        "required": [
          "intent"
        ],
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/BookingIntentView"
          }
        }
      },
      "BookingIntentView": {
        "description": "Read-only projection of a booking intent. Omits customer_support_code, promo_code and passenger PII; those fields are returned once at intent-creation and /book time.",
        "type": "object",
        "required": [
          "id",
          "funding_wallet",
          "refund_wallet",
          "offer_id",
          "expected_ticket_amount",
          "expected_ticket_currency",
          "expected_escrow_amount",
          "expected_escrow_mint",
          "fee_amount",
          "status",
          "expires_at",
          "escrow_slot_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "intent_0000000000000000"
          },
          "promo_code": {
            "type": "string",
            "description": "Present on the intent-creation answer only, when a discount code (sent as promo_code, or redeemed earlier by this wallet) waived the fee. Absent from GET /air/intents/{intent_id}."
          },
          "funding_wallet": {
            "type": "string"
          },
          "refund_wallet": {
            "type": "string"
          },
          "offer_id": {
            "type": "string"
          },
          "expected_ticket_amount": {
            "type": "integer",
            "format": "int64"
          },
          "expected_ticket_currency": {
            "type": "string",
            "example": "USD"
          },
          "expected_escrow_amount": {
            "type": "integer",
            "format": "int64"
          },
          "expected_escrow_mint": {
            "type": "string"
          },
          "fee_amount": {
            "type": "integer",
            "format": "int64"
          },
          "passenger_count": {
            "type": "integer",
            "description": "How many passengers the offer was priced for; /air/book must supply exactly this many."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "booked",
              "refunded"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "escrow_slot_id": {
            "type": "integer",
            "format": "int64"
          },
          "escrow_address": {
            "type": "string"
          },
          "vault_address": {
            "type": "string"
          },
          "escrow_init_signature": {
            "type": "string"
          },
          "escrow_initialized_at": {
            "type": "string",
            "format": "date-time"
          },
          "observed_escrow_amount": {
            "type": "integer",
            "format": "int64"
          },
          "observed_escrow_mint": {
            "type": "string"
          },
          "escrow_funded_at": {
            "type": "string",
            "format": "date-time"
          },
          "airline_order_id": {
            "type": "string"
          },
          "booking_reference": {
            "type": "string",
            "description": "The airline PNR, present once the ticket is issued (Duffel: when the order is paid; browser tiers: when the supplier's ticket email arrives, which can take a few hours). Show it to the traveller: it is what they check in with. Poll this endpoint until it appears; no other call is needed.",
            "example": "ABC123"
          },
          "payment_required_by": {
            "type": "string",
            "format": "date-time"
          },
          "ticketed_at": {
            "type": "string",
            "format": "date-time"
          },
          "capture_tx_hash": {
            "type": "string"
          },
          "captured_at": {
            "type": "string",
            "format": "date-time"
          },
          "refund_reason": {
            "type": "string"
          },
          "refund_tx_hash": {
            "type": "string"
          },
          "refunded_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BookingIntent": {
        "type": "object",
        "required": [
          "id",
          "customer_support_code",
          "funding_wallet",
          "refund_wallet",
          "offer_id",
          "expected_ticket_amount",
          "expected_ticket_currency",
          "expected_escrow_amount",
          "expected_escrow_mint",
          "fee_amount",
          "status",
          "expires_at",
          "escrow_slot_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "intent_0000000000000000"
          },
          "customer_support_code": {
            "type": "string",
            "example": "BRIJ-RA2T-CYTR"
          },
          "funding_wallet": {
            "type": "string"
          },
          "refund_wallet": {
            "type": "string"
          },
          "offer_id": {
            "type": "string"
          },
          "expected_ticket_amount": {
            "type": "integer",
            "format": "int64"
          },
          "expected_ticket_currency": {
            "type": "string",
            "example": "USD"
          },
          "expected_escrow_amount": {
            "type": "integer",
            "format": "int64"
          },
          "expected_escrow_mint": {
            "type": "string"
          },
          "fee_amount": {
            "type": "integer",
            "format": "int64"
          },
          "passenger_count": {
            "type": "integer",
            "description": "How many passengers the offer was priced for; /air/book must supply exactly this many."
          },
          "passenger_given_name": {
            "type": "string"
          },
          "passenger_family_name": {
            "type": "string"
          },
          "passenger_born_on": {
            "type": "string",
            "format": "date"
          },
          "passenger_title": {
            "type": "string"
          },
          "passenger_gender": {
            "type": "string"
          },
          "passenger_email": {
            "type": "string"
          },
          "passenger_phone_number": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "booked",
              "refunded"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "escrow_slot_id": {
            "type": "integer",
            "format": "int64"
          },
          "escrow_address": {
            "type": "string"
          },
          "vault_address": {
            "type": "string"
          },
          "escrow_init_signature": {
            "type": "string"
          },
          "escrow_initialized_at": {
            "type": "string",
            "format": "date-time"
          },
          "observed_escrow_amount": {
            "type": "integer",
            "format": "int64"
          },
          "observed_escrow_mint": {
            "type": "string"
          },
          "escrow_funded_at": {
            "type": "string",
            "format": "date-time"
          },
          "airline_order_id": {
            "type": "string"
          },
          "payment_required_by": {
            "type": "string",
            "format": "date-time"
          },
          "ticketed_at": {
            "type": "string",
            "format": "date-time"
          },
          "capture_tx_hash": {
            "type": "string"
          },
          "captured_at": {
            "type": "string",
            "format": "date-time"
          },
          "refund_reason": {
            "type": "string"
          },
          "refund_tx_hash": {
            "type": "string"
          },
          "refunded_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PassengerInput": {
        "type": "object",
        "description": "Passenger details. Field constraints mirror the upstream airline contract; values the airline would reject (e.g. gender other than 'm'/'f') are rejected by this API before settling x402, so funds stay in the agent's wallet on validation failure.",
        "required": [
          "given_name",
          "family_name",
          "born_on",
          "title",
          "gender",
          "email",
          "phone_number"
        ],
        "properties": {
          "given_name": {
            "type": "string",
            "description": "Given (first) name as on the travel document.",
            "example": "Antoine"
          },
          "family_name": {
            "type": "string",
            "description": "Family (last) name as on the travel document.",
            "example": "Herzog"
          },
          "born_on": {
            "type": "string",
            "format": "date",
            "description": "Date of birth in ISO 8601 (YYYY-MM-DD).",
            "example": "1990-04-12"
          },
          "title": {
            "type": "string",
            "description": "Honorific. Lowercase, exactly one of the allowed values.",
            "enum": [
              "mr",
              "mrs",
              "ms",
              "miss",
              "dr"
            ],
            "example": "mr"
          },
          "gender": {
            "type": "string",
            "description": "Biological sex as recorded on the travel document. Lowercase, exactly 'm' or 'f' (the airline does not accept other values).",
            "enum": [
              "m",
              "f"
            ],
            "example": "m"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Contact email. Receives booking-in-progress and booking-confirmed notifications.",
            "example": "passenger@example.com"
          },
          "phone_number": {
            "type": "string",
            "description": "Phone number in E.164 format (leading '+', country code, no spaces or punctuation).",
            "pattern": "^\\+[1-9]\\d{6,14}$",
            "example": "+447400123456"
          },
          "nationality": {
            "type": "string",
            "description": "Only when a supplier asks for it; ignored otherwise. Passenger nationality as a country name in English, e.g. \"France\" — the supplier's booking form demands the travel document up front."
          },
          "passport_number": {
            "type": "string",
            "description": "Only when a supplier asks for it; ignored otherwise. Passport or national ID number."
          },
          "passport_expiry": {
            "type": "string",
            "format": "date",
            "description": "Only when a supplier asks for it; ignored otherwise. Document expiry, YYYY-MM-DD, must be in the future. Missing/expired documents are refused BEFORE payment (400 travel_document_required / travel_document_expired)."
          }
        }
      },
      "RequestBookingResponse": {
        "type": "object",
        "required": [
          "intent",
          "booking"
        ],
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/BookingIntent"
          },
          "booking": {
            "$ref": "#/components/schemas/BookResult"
          }
        }
      },
      "BookResult": {
        "type": "object",
        "required": [
          "order_id",
          "total_amount",
          "total_currency",
          "awaiting_payment",
          "documents_issued"
        ],
        "properties": {
          "order_id": {
            "type": "string"
          },
          "total_amount": {
            "type": "integer",
            "format": "int64"
          },
          "total_currency": {
            "type": "string"
          },
          "awaiting_payment": {
            "type": "boolean"
          },
          "documents_issued": {
            "type": "integer"
          },
          "payment_required_by": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrderResponse": {
        "type": "object",
        "required": [
          "order"
        ],
        "properties": {
          "order": {
            "$ref": "#/components/schemas/OrderStatus"
          }
        }
      },
      "OrderStatus": {
        "type": "object",
        "required": [
          "order_id",
          "total_amount_decimal",
          "total_amount",
          "total_currency",
          "awaiting_payment",
          "documents_issued"
        ],
        "properties": {
          "order_id": {
            "type": "string"
          },
          "booking_reference": {
            "type": "string"
          },
          "total_amount_decimal": {
            "type": "string"
          },
          "total_amount": {
            "type": "integer",
            "format": "int64"
          },
          "total_currency": {
            "type": "string"
          },
          "awaiting_payment": {
            "type": "boolean"
          },
          "documents_issued": {
            "type": "integer"
          },
          "price_guarantee_expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "payment_required_by": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BookRequest": {
        "type": "object",
        "required": [
          "intent_id",
          "passengers"
        ],
        "properties": {
          "intent_id": {
            "type": "string",
            "description": "Id returned by POST /air/intents.",
            "example": "intent_0000000000000000"
          },
          "passengers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 9,
            "items": {
              "$ref": "#/components/schemas/PassengerInput"
            },
            "description": "Exactly as many passengers as the intent's passenger_count (= adults searched), LEAD PASSENGER FIRST. Positions map to the offer's travellers. The lead passenger receives all emails, and refund requests authenticate against the LEAD passenger's family name. Duplicate travellers (same name and birth date) are refused with 400 duplicate_passenger. All refunds are all-or-nothing: one booking = one escrow, there is no per-passenger cancellation."
          }
        }
      },
      "OfferSegment": {
        "type": "object",
        "description": "One flight leg of an offer. Times are in the airport's local timezone and carry no UTC offset.",
        "required": [
          "origin_iata",
          "destination_iata",
          "departing_at",
          "arriving_at",
          "origin_time_zone",
          "destination_time_zone",
          "technical_stops"
        ],
        "properties": {
          "origin_iata": {
            "type": "string",
            "example": "JFK"
          },
          "destination_iata": {
            "type": "string",
            "example": "DFW"
          },
          "departing_at": {
            "type": "string",
            "description": "Airport-local time, no UTC offset.",
            "example": "2026-08-02T14:42:00"
          },
          "arriving_at": {
            "type": "string",
            "description": "Airport-local time, no UTC offset.",
            "example": "2026-08-02T17:44:00"
          },
          "origin_time_zone": {
            "type": "string",
            "description": "IANA timezone of the origin airport; combine with departing_at for an absolute instant.",
            "example": "America/New_York"
          },
          "destination_time_zone": {
            "type": "string",
            "description": "IANA timezone of the destination airport; combine with arriving_at for an absolute instant.",
            "example": "America/Chicago"
          },
          "duration": {
            "type": "string",
            "description": "Leg duration, ISO 8601 (e.g. PT1H15M). Precomputed — never subtract the naive local timestamps.",
            "example": "PT1H15M"
          },
          "carrier_name": {
            "type": "string",
            "example": "American Airlines"
          },
          "flight_number": {
            "type": "string",
            "example": "1953"
          },
          "marketing_carrier_name": {
            "type": "string",
            "description": "Airline SELLING this leg. Differs from carrier_name (the operating airline) on codeshares — e.g. sold by British Airways, operated by Iberia Express. Explains same-flight offers priced differently by seller.",
            "example": "British Airways"
          },
          "carrier_iata": {
            "type": "string",
            "description": "IATA code of the operating airline (carrier_name) — the stable identifier where the name is a display string.",
            "example": "IB"
          },
          "marketing_carrier_iata": {
            "type": "string",
            "description": "IATA code of the selling airline (marketing_carrier_name).",
            "example": "BA"
          },
          "operating_flight_number": {
            "type": "string",
            "description": "Operating carrier's own flight number; flight_number is the marketed one shown on the boarding pass.",
            "example": "1692"
          },
          "aircraft_name": {
            "type": "string",
            "example": "Airbus A320"
          },
          "origin_terminal": {
            "type": "string",
            "example": "1"
          },
          "destination_terminal": {
            "type": "string",
            "example": "4"
          },
          "fare_basis_code": {
            "type": "string",
            "description": "Airline fare basis identifier for this leg.",
            "example": "ADYO5L"
          },
          "technical_stops": {
            "type": "integer",
            "description": "Refuelling-type stops on this leg WITHOUT a plane change. A leg with technical stops is still one segment; truly non-stop means stops == 0 AND technical_stops == 0."
          },
          "technical_stop_airports": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IATA codes of the technical-stop airports, in order."
          }
        }
      },
      "FareConditions": {
        "type": "object",
        "description": "What the fare permits before departure. Every field of the parent offer is emitted; null on an *_allowed field means the airline did not disclose it — treat as unknown, do NOT assume false. Penalty amounts are decimal strings in the given currency; \"0\" means free.",
        "properties": {
          "change_allowed": {
            "type": "boolean",
            "nullable": true,
            "description": "true = changeable (see penalty), false = not changeable, null = airline did not say."
          },
          "change_penalty_amount": {
            "type": "string",
            "description": "Decimal fee to change, \"0\" = free change. Absent when unknown.",
            "example": "0"
          },
          "change_penalty_currency": {
            "type": "string",
            "example": "USD"
          },
          "refund_allowed": {
            "type": "boolean",
            "nullable": true,
            "description": "true = refundable before departure (see penalty), false = non-refundable, null = airline did not say."
          },
          "refund_penalty_amount": {
            "type": "string",
            "description": "Decimal fee to refund, \"0\" = free refund. Absent when unknown.",
            "example": "0"
          },
          "refund_penalty_currency": {
            "type": "string",
            "example": "USD"
          }
        }
      },
      "OfferService": {
        "type": "object",
        "description": "One purchasable ancillary on an offer. INFORMATIONAL ONLY: services cannot be bought through this API — use these prices to compare a bare fare plus a paid bag against a fare that already includes one.",
        "required": [
          "type",
          "maximum_quantity",
          "total_amount_decimal",
          "total_currency"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Service family, e.g. baggage.",
            "example": "baggage"
          },
          "baggage_type": {
            "type": "string",
            "description": "For baggage services: checked or carry_on.",
            "example": "checked"
          },
          "maximum_weight_kg": {
            "type": "integer",
            "nullable": true,
            "example": 23
          },
          "maximum_quantity": {
            "type": "integer",
            "example": 3
          },
          "total_amount_decimal": {
            "type": "string",
            "description": "Price PER UNIT of the service.",
            "example": "45.00"
          },
          "total_currency": {
            "type": "string",
            "example": "USD"
          }
        }
      },
      "OfferDetailsRequest": {
        "type": "object",
        "required": [
          "offer_id"
        ],
        "properties": {
          "offer_id": {
            "type": "string",
            "description": "id from POST /air/search.",
            "example": "fastbooking:off_0000000000000000000000"
          }
        }
      },
      "OfferDetailsResponse": {
        "type": "object",
        "required": [
          "offer",
          "available_services"
        ],
        "properties": {
          "offer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OfferSummary"
              }
            ],
            "description": "The offer re-fetched live: total_amount and expires_at are CURRENT, unlike a minutes-old search result."
          },
          "available_services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferService"
            },
            "description": "Purchasable extras with prices. Empty array = the airline offers none on this fare (an answer, not missing data)."
          }
        }
      },
      "OfferSlice": {
        "type": "object",
        "description": "One direction of the journey: the outbound, and for round trips the inbound. Same semantics as the journey-level fields (whole-direction endpoints, airport-local times, stops = plane changes).",
        "required": [
          "origin_iata",
          "destination_iata",
          "departing_at",
          "arriving_at",
          "origin_time_zone",
          "destination_time_zone",
          "stops",
          "segments"
        ],
        "properties": {
          "origin_iata": {
            "type": "string",
            "example": "MAD"
          },
          "destination_iata": {
            "type": "string",
            "example": "LIS"
          },
          "departing_at": {
            "type": "string",
            "description": "Airport-local, no UTC offset.",
            "example": "2026-08-07T10:20:00"
          },
          "arriving_at": {
            "type": "string",
            "example": "2026-08-07T11:35:00"
          },
          "origin_time_zone": {
            "type": "string",
            "example": "Europe/Madrid"
          },
          "destination_time_zone": {
            "type": "string",
            "example": "Europe/Lisbon"
          },
          "duration": {
            "type": "string",
            "example": "PT1H15M"
          },
          "stops": {
            "type": "integer"
          },
          "technical_stops": {
            "type": "integer"
          },
          "fare_brand_name": {
            "type": "string"
          },
          "checked_bags_included": {
            "type": "integer",
            "nullable": true,
            "description": "Checked bags included on THIS direction (minimum across its legs; null when a leg does not report it). A round trip can mix brands per direction, and the journey-level checked_bags_included is then the minimum of the two."
          },
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferSegment"
            }
          }
        }
      },
      "OfferFareOption": {
        "type": "object",
        "description": "Compact form of one fare inside a grouped result: enough to answer refundability, changeability, baggage and price questions without another search, and to act on the fare via its offer_id. refundable/changeable keep the null-means-undisclosed semantics.",
        "required": [
          "offer_id",
          "total_amount_decimal",
          "total_currency",
          "refundable",
          "changeable",
          "checked_bags_included"
        ],
        "properties": {
          "offer_id": {
            "type": "string"
          },
          "fare_brand_name": {
            "type": "string",
            "example": "Comfort Balearic"
          },
          "total_amount_decimal": {
            "type": "string",
            "example": "265.30"
          },
          "total_currency": {
            "type": "string",
            "example": "USD"
          },
          "refundable": {
            "type": "boolean",
            "nullable": true,
            "description": "null = airline did not say."
          },
          "changeable": {
            "type": "boolean",
            "nullable": true
          },
          "checked_bags_included": {
            "type": "integer",
            "nullable": true
          },
          "change_penalty_amount": {
            "type": "string",
            "description": "Fee the airline states for a change before departure, when changeable = true and a fee is disclosed (e.g. \"190.00\"). Absent when free, unknown, or not changeable.",
            "example": "190.00"
          },
          "change_penalty_currency": {
            "type": "string",
            "example": "USD"
          },
          "refund_penalty_amount": {
            "type": "string",
            "description": "Fee the airline states for a refund before departure, when refundable = true and a fee is disclosed. Absent when free, unknown, or non-refundable."
          },
          "refund_penalty_currency": {
            "type": "string"
          },
          "directions": {
            "type": "array",
            "description": "Round trips only: the brand and checked allowance of each direction in order (outbound, inbound). This is what differs between \"Standard Economy / Basic Economy\" and \"Basic Economy / Standard Economy\" at the same price — the journey-level checked_bags_included is the minimum of the two. Absent on one-ways and on browser-tier menus.",
            "items": {
              "type": "object",
              "required": [
                "fare_brand_name",
                "checked_bags_included"
              ],
              "properties": {
                "fare_brand_name": {
                  "type": "string",
                  "example": "Standard Economy"
                },
                "checked_bags_included": {
                  "type": "integer",
                  "nullable": true
                }
              }
            }
          },
          "cabin": {
            "type": "string",
            "description": "browser tier only: cabin label from the supplier's fare menu."
          },
          "seats_left": {
            "type": "integer",
            "nullable": true,
            "description": "browser tier only: seats remaining at this fare, when the supplier discloses it."
          },
          "conditions": {
            "type": "array",
            "description": "browser tier only: the supplier's verbatim condition notes (baggage, refund policy).",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "fare_index": {
            "type": "integer",
            "description": "browser tier only: the fare's position in the supplier's menu - the index the book flow selects. The row's offer_id embeds it."
          }
        }
      },
      "SearchUpdatesRequest": {
        "type": "object",
        "required": [
          "search_id"
        ],
        "properties": {
          "search_id": {
            "type": "string",
            "description": "The search_id returned by POST /air/search.",
            "example": "srch_2f7c1de09ab34455ee01aa8b90c2d711"
          }
        }
      },
      "SearchUpdatesResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "enriching"
            ],
            "description": "\"complete\" once no further offers can arrive."
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferSummary"
            },
            "description": "The FULL merged offer list so far (not a delta), deduplicated across fulfiller tiers, shaped exactly like the original search request."
          },
          "fulfillers": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "complete",
                "running"
              ]
            },
            "description": "Per-tier quoting state."
          },
          "matched_count": {
            "type": "integer",
            "description": "How many offers survived the filters and grouping BEFORE the limit cut — what a full listing would hold."
          },
          "highlights": {
            "$ref": "#/components/schemas/SearchHighlights"
          },
          "new_since_last_poll": {
            "type": "integer",
            "description": "How many offers landed since the previous poll (all of them on the first poll)."
          },
          "poll_after_ms": {
            "type": "integer",
            "description": "Suggested delay before the next poll. Absent when complete."
          },
          "next": {
            "type": "string",
            "description": "Present while status is enriching: keep polling until complete before choosing. Absent when complete."
          }
        }
      },
      "RailSearchResponse": {
        "type": "object",
        "properties": {
          "journeys": {
            "type": "array",
            "description": "Journeys, cheapest first.",
            "items": {
              "type": "object",
              "properties": {
                "journey_id": {
                  "type": "string",
                  "description": "Send it back EXACTLY to POST /rail/quote."
                },
                "merchant": {
                  "type": "string",
                  "description": "The rail merchant (its domain)."
                },
                "title": {
                  "type": "string"
                },
                "summary": {
                  "type": "object",
                  "description": "Times, stations, changes."
                },
                "price_from": {
                  "type": "string",
                  "description": "The merchant's own price, in merchant_currency."
                },
                "merchant_currency": {
                  "type": "string"
                },
                "total_from": {
                  "type": "string",
                  "description": "ALL-IN price in USDC (conversion + fee included)."
                },
                "total_currency": {
                  "type": "string"
                }
              }
            }
          },
          "adults": {
            "type": "integer",
            "description": "Travellers searched; the buy names exactly this many."
          },
          "pending_merchants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Merchants still searching (retry the same request)."
          },
          "above_limit": {
            "type": "integer",
            "description": "Journeys hidden because their total is above the per-order limit."
          },
          "order_limit": {
            "type": "string",
            "description": "The per-order limit, USDC."
          }
        }
      },
      "PurchaseQuote": {
        "type": "object",
        "properties": {
          "offer_id": {
            "type": "string",
            "description": "Pass it to POST /rail/intents or /shop/intents, exactly as received. Valid ~20 min (expires_at)."
          },
          "merchant": {
            "type": "string"
          },
          "product": {
            "type": "object",
            "description": "What is being bought, as the merchant names it."
          },
          "quantity": {
            "type": "integer"
          },
          "breakdown": {
            "type": "object",
            "description": "What the merchant itself charges (items, shipping, tax), in merchant_currency."
          },
          "merchant_currency": {
            "type": "string"
          },
          "fx": {
            "type": "object",
            "description": "When the merchant is not USD: ECB rate, conversion margin, merchant_usd."
          },
          "shipping_method": {
            "type": "string"
          },
          "delivery_estimate": {
            "type": "string"
          },
          "total_amount": {
            "type": "string",
            "description": "ALL-IN price in USDC: the escrow amount."
          },
          "total_currency": {
            "type": "string"
          },
          "fee_amount": {
            "type": "string",
            "description": "BRIJ's fee, included in total_amount."
          },
          "requires": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What the buy must provide (person, document, contact.phone…)."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "ship_countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Instant quotes: the countries ship_to.country may be (ISO 3166 alpha-2). One entry for a store whose domain names its country (amazon.de); every euro-area country for a euro store whose domain names none (on.com); absent when the store's country is unknown, in which case the buyer names it."
          },
          "ship_country": {
            "type": "string",
            "description": "The single country this order ships to, or for a multi-market store the market its product link named (a default the buyer may change within ship_countries)."
          }
        }
      },
      "PurchaseOrder": {
        "type": "object",
        "properties": {
          "intent_id": {
            "type": "string"
          },
          "merchant": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "purchasing → ordered (merchant reference) → confirmed (captured) | refunded."
          },
          "merchant_order_number": {
            "type": "string",
            "description": "The merchant's order number / booking reference."
          },
          "tracking_number": {
            "type": "string"
          },
          "shipped_at": {
            "type": "string",
            "format": "date-time"
          },
          "merchant_total": {
            "type": "string"
          },
          "escrow_amount": {
            "type": "string"
          },
          "captured_at": {
            "type": "string",
            "format": "date-time"
          },
          "refunded_at": {
            "type": "string",
            "format": "date-time"
          },
          "service_ends_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PurchaseBuyResponse": {
        "type": "object",
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/BookingIntent"
          },
          "status": {
            "type": "string",
            "description": "purchasing: the merchant is being paid; follow with the orders endpoint."
          }
        }
      },
      "HotelSearchRequest": {
        "type": "object",
        "properties": {
          "city_id": {
            "type": "string",
            "description": "A city_id from GET /hotels/places."
          },
          "location": {
            "type": "string",
            "description": "A city name, when no city_id or coordinates are sent."
          },
          "latitude": {
            "type": "number",
            "description": "Latitude of the place, with longitude, instead of a city."
          },
          "longitude": {
            "type": "number",
            "description": "Longitude of the place."
          },
          "radius_km": {
            "type": "integer",
            "description": "Around the coordinates, default 10."
          },
          "check_in_date": {
            "type": "string",
            "example": "2026-12-10",
            "description": "Check-in day, YYYY-MM-DD."
          },
          "check_out_date": {
            "type": "string",
            "example": "2026-12-12",
            "description": "Check-out day, YYYY-MM-DD, at most 30 nights later."
          },
          "rooms": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "description": "Rooms, default 1."
          },
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8,
            "description": "Adults in total, default 1."
          },
          "child_ages": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "One age per child, up to 4."
          },
          "free_cancellation_only": {
            "type": "boolean",
            "description": "Only hotels with a free-cancellation rate."
          },
          "stars": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5
            },
            "description": "Keep hotels with one of these star ratings, e.g. [4, 5]. Unrated hotels are left out when set."
          },
          "sort": {
            "type": "string",
            "enum": [
              "price",
              "price_desc"
            ],
            "description": "Order by the all-in total: price (default, cheapest first) or price_desc. Applied before the 50-hotel cap."
          },
          "accommodation_id": {
            "type": "string",
            "description": "Search ONE hotel: an accommodation_id from GET /hotels/places (hotels[]), instead of a place."
          }
        },
        "required": [
          "check_in_date",
          "check_out_date"
        ]
      },
      "HotelBookRequest": {
        "type": "object",
        "required": [
          "intent_id",
          "guests",
          "email",
          "phone_number"
        ],
        "properties": {
          "intent_id": {
            "type": "string",
            "example": "intent_0000000000000000",
            "description": "The intent id returned by POST /hotels/intents."
          },
          "guests": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "given_name",
                "family_name"
              ],
              "properties": {
                "given_name": {
                  "type": "string",
                  "description": "Given (first) name."
                },
                "family_name": {
                  "type": "string",
                  "description": "Family name."
                },
                "born_on": {
                  "type": "string",
                  "description": "YYYY-MM-DD, required for a child."
                }
              }
            },
            "description": "The lead guest first (the reservation's name and the identity for a cancellation), then at least one guest per room."
          },
          "email": {
            "type": "string",
            "description": "The lead guest's email address: the confirmation goes there. Ask the guest for it by name (\"your email address\"), never as \"contact details\"."
          },
          "phone_number": {
            "type": "string",
            "description": "The lead guest's mobile number WITH its country code, E.164 (e.g. +447400123456). Ask the guest for it by name (\"your phone number, with country code\"): the hotel calls it."
          },
          "special_requests": {
            "type": "string",
            "description": "Forwarded to the hotel (early check-in, cot)."
          }
        }
      },
      "HotelSearchResponse": {
        "type": "object",
        "description": "A hotel search.",
        "properties": {
          "place": {
            "description": "The place searched."
          },
          "check_in_date": {
            "description": ""
          },
          "check_out_date": {
            "description": ""
          },
          "nights": {
            "description": ""
          },
          "party": {
            "description": "rooms, adults, children."
          },
          "hotels": {
            "description": "Cheapest first: hotel_id, name, rating, review_score, address, distance_km, price_from, total_from (ALL-IN), due_at_hotel_from, currency."
          }
        },
        "additionalProperties": true
      },
      "HotelRatesResponse": {
        "type": "object",
        "description": "A hotel's rooms and rates.",
        "properties": {
          "hotel_id": {
            "description": ""
          },
          "hotel": {
            "description": "Name, address, rating, check-in/out times."
          },
          "room_types": {
            "description": "Each room: name, beds, rates[] (rate_id, board, refundable, refundability, cancellation_timeline, price)."
          },
          "seller": {
            "description": "Who sells the stay (BRIJ)."
          }
        },
        "additionalProperties": true
      },
      "HotelStay": {
        "type": "object",
        "description": "A quoted stay.",
        "properties": {
          "offer_id": {
            "description": "Pass to POST /hotels/intents."
          },
          "quote_id": {
            "description": ""
          },
          "hotel": {
            "description": ""
          },
          "room": {
            "description": ""
          },
          "rate": {
            "description": "Board, refundability, cancellation_timeline, conditions."
          },
          "check_in_date": {
            "description": ""
          },
          "check_out_date": {
            "description": ""
          },
          "nights": {
            "description": ""
          },
          "party": {
            "description": ""
          },
          "price": {
            "description": "hotel_total (tax and fees included), service_fee, total_amount (ALL-IN, what the escrow holds), due_at_hotel_amount."
          },
          "seller": {
            "description": ""
          }
        },
        "additionalProperties": true
      },
      "HotelConfirmation": {
        "type": "object",
        "description": "A hotel booking.",
        "properties": {
          "booking_id": {
            "description": ""
          },
          "status": {
            "description": "awaiting_payment, booking, confirmed, failed, cancelled."
          },
          "reference": {
            "description": "The hotel's booking reference."
          },
          "confirmed_at": {
            "description": ""
          },
          "cancelled_at": {
            "description": ""
          },
          "stay": {
            "description": "The stay as quoted."
          },
          "guests": {
            "description": ""
          },
          "email": {
            "description": ""
          }
        },
        "additionalProperties": true
      },
      "HotelBookResponse": {
        "type": "object",
        "description": "A hotel booking accepted.",
        "properties": {
          "intent_id": {
            "description": ""
          },
          "status": {
            "description": "booking: poll POST /hotels/orders."
          },
          "booking": {
            "description": "The booking record (HotelConfirmation)."
          }
        },
        "additionalProperties": true
      },
      "HotelOrder": {
        "type": "object",
        "description": "A hotel booking's status.",
        "properties": {
          "intent_id": {
            "description": ""
          },
          "status": {
            "description": "awaiting_payment, booking, confirmed, failed, cancelled, refunded."
          },
          "booking_reference": {
            "description": ""
          },
          "escrow_amount": {
            "description": ""
          },
          "captured_at": {
            "description": ""
          },
          "refunded_at": {
            "description": ""
          },
          "booking": {
            "description": "The full confirmation (HotelConfirmation)."
          }
        },
        "additionalProperties": true
      }
    }
  },
  "info": {
    "title": "BRIJ Travel API",
    "version": "1.0.0",
    "contact": {
      "name": "BRIJ Travel support",
      "email": "support@brij.fi",
      "url": "https://travel.brij.fi"
    },
    "description": "Payments for AI agents: book flights (/air/*) and hotels (/hotels/*), paid per\ncall with x402 in USDC on Solana, with escrow-backed booking and automatic\nrefunds. Also: rent a disposable Linux computer + browser by the minute\n(/sandbox/*).\n\n`POST /air/search` accepts either a valid x402 `PAYMENT-SIGNATURE` or a\nBRIJ gateway sponsored-preview signature. `POST /air/intents`,\n`POST /air/book`, and `POST /air/refund-requests` are protected by x402.\nClients that do not send a valid `PAYMENT-SIGNATURE` header receive\n`402 Payment Required` with a `PAYMENT-REQUIRED` header and JSON payment\nrequirements body.\n\nAction endpoints (POST /air/book, POST /air/refund-requests) take intent_id\nin the request body — never in the path. The two reads are path-addressed:\nGET /air/intents/{intent_id} and GET /air/orders/{order_id}.\n\n**What a booking costs.** The flight's price is ONE figure: an offer's total_amount, which is exactly the expected_escrow_amount POST /air/book pays (booking fee included). The x402 calls around it are billed separately, each on its own: /air/search 0.10 USDC (more under load), /air/offer-details 0.01, /air/intents 0.10, /air/orders 0.01. So a wallet's total spend is the escrow amount plus a few tenths — e.g. 775.72 escrow + 0.10 intent + 2 × 0.10 searches = 776.02 USDC. When quoting the traveller a price, quote the escrow amount and say the call fees are separate.\n",
    "x-guidance": "Flights in four steps, each paid per call with x402 (USDC on Solana).\n\n1. POST /air/search — find live offers. Price is dynamic: 0.10 USDC x1..50 depending on load, so always read the current PAYMENT-REQUIRED challenge rather than reusing a price you saw earlier.\n2. POST /air/intents — lock one offer_id and derive its escrow. Costs 0.10 USDC. The response carries the intent id, the customer_support_code (PERSIST BOTH — the support code cannot be re-read later and is required to read the order or request a refund) and passenger_count: how many passengers /air/book must supply.\n3. POST /air/book — send intent_id and exactly passenger_count passengers in the body, LEAD PASSENGER FIRST (the lead receives all emails and is the identity for refund requests; duplicate travellers are refused). The price is this intent's escrow amount, i.e. the ticket total for all passengers, quoted in the challenge. Booking is asynchronous: a 200 means the request was accepted, then poll GET /air/intents/{intent_id} until status is booked or refunded.\n4. POST /air/refund-requests — optional, 0.10 USDC. Needs intent_id in the body plus the X-Customer-Support-Code header and X-Passenger-Family-Name: the LEAD passenger's family name. It files a request for manual review; it does not execute a refund.\n\nAction POSTs never take an id in the path: send intent_id in the request body of POST /air/book and POST /air/refund-requests. The two GET reads (GET /air/intents/{intent_id}, GET /air/orders/{order_id}) are path-addressed. If the upstream price moved between steps 2 and 3 the booking is rejected and the escrow is refunded automatically to the refund wallet frozen at intent creation.\n\nTo drill into one offer (fresh price/expiry, paid-ancillary prices such as extra bags), POST /air/offer-details with the offer_id — cheaper than re-searching. Seat maps and legal fare-rule text remain unobtainable: when a decision depends on them, say so to the customer rather than guessing.\n\nNever answer \"no fare with property X exists\" from a truncated ungrouped search: pricier variants (refundable, with bags, higher cabin) sort to the tail and fall off. Use cheapest_per_itinerary=true and read fare_options.\n\nHotels follow the same escrow: POST /hotels/search (0.10, all-in total_from per hotel; GET /hotels/places?q= is free) → POST /hotels/rates {hotel_id} (0.01) → POST /hotels/quote {rate_id} (0.01, returns offer_id \"hotel:\u003cquote_id\u003e\") → POST /hotels/intents {offer_id, funding_wallet} (0.10, PERSIST customer_support_code) → POST /hotels/book {intent_id, guests (lead first, one per room at least), email, phone_number} paying the intent's escrow amount → POST /hotels/orders {intent_id} + X-Customer-Support-Code (0.01) until confirmed. A refused booking refunds in full automatically; POST /hotels/cancel cancels and files the refund the hotel's cancellation terms allow. Tell the guest what is due at the hotel on top of the total (due_at_hotel_amount + due_at_hotel_currency on the quote, e.g. city tax)."
  },
  "openapi": "3.1.0",
  "paths": {
    "/affiliates": {
      "post": {
        "summary": "Get your referral code (free, idempotent)",
        "description": "Free. {wallet} → {code, link}. One short code per Solana wallet — share app.brij.fi/?ref=\u003ccode\u003e (or pass referrer on POST /air/intents). Referred bookings credit 20% of the platform fee to your wallet — earned when the booking captures (ticket actually issued), vested only once the journey has been flown with no refund issued (pending until then). Statement: GET /affiliates/{code}. Payouts are periodic USDC transfers once the balance clears the minimum.",
        "responses": {
          "200": {
            "description": "{code, link}"
          }
        }
      }
    },
    "/affiliates/{code}": {
      "get": {
        "summary": "Read the statement of an affiliate code.",
        "description": "Free, public, self-serve: referred captured bookings, referred vested bookings (flown, unrefunded), accrued (vested), pending (not flown yet), paid, balance (micros USDC) and the share_bps.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The referral code returned by POST /affiliates: 8 lower-case characters, no 0/O/1/l/i.",
            "schema": {
              "type": "string",
              "pattern": "^[a-hjkmnp-z2-9]{8}$"
            },
            "example": "k7mqt9rv"
          }
        ],
        "responses": {
          "200": {
            "description": "The statement"
          },
          "404": {
            "description": "unknown code"
          }
        }
      }
    },
    "/air/airlines": {
      "get": {
        "tags": [
          "air"
        ],
        "operationId": "listAirlines",
        "summary": "Supported airlines (free).",
        "description": "Free, no auth. Carrier catalog: source \"api\" is the API-settled (Duffel) catalog, refreshed at most daily. Presence is recognition, not a bookability promise: what is bookable for a route is what POST /air/search returns.",
        "responses": {
          "200": {
            "description": "The catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "airlines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "iata_code": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "\"api\" and/or fulfiller tier names that quoted the carrier"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "refreshed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "coverage": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/air/book": {
      "post": {
        "tags": [
          "intents"
        ],
        "operationId": "bookIntent",
        "summary": "Pay the escrow and request booking.",
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "10.00",
            "max": "10000.00",
            "note": "the price IS the intent's expected_escrow_amount — the fare held in escrow, not a fee"
          }
        },
        "description": "The intent id travels in the request body; the resource URL is static. Paid x402 endpoint. The payment challenge is dynamic for the intent:\n`payTo` is the intent escrow address, `asset` is the expected escrow\nmint, and `amount` is the expected escrow amount.\n\nAfter x402 settlement, the API records the passenger list (lead first), verifies exact\nescrow funding on-chain, and enqueues the booking worker. Airline payment\nand escrow capture happen asynchronously.\n\nIf booking fails after x402 settlement, retry the same `/book` call;\nexcess funds remain refundable to `refund_wallet`.\n\nBooking is asynchronous: poll GET /air/intents/{intent_id} until booked or refunded.",
        "security": [
          {
            "x402PaymentSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookRequest"
              },
              "example": {
                "intent_id": "intent_0000000000000000",
                "passengers": [
                  {
                    "given_name": "Jane",
                    "family_name": "Doe",
                    "born_on": "1990-01-01",
                    "title": "ms",
                    "gender": "f",
                    "email": "jane.doe@example.com",
                    "phone_number": "+15551234567"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking sync job queued.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestBookingResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid passenger data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Intent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Intent is not active, `intent_expired` if its booking window has closed (create a new intent from a fresh offer; detail carries `expired_at`), `offer_expired` if the offer has left the airline's inventory, `offer_repriced` if its live price no longer matches the intent (detail carries `expected_ticket_amount` and `current_ticket_amount`) — both checked live against the airline BEFORE settlement, so the refusal is free — escrow is missing, funding is not exact, or `booking_already_requested` if a prior /book succeeded for this intent (retry has no effect; the worker is processing it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "501": {
            "description": "Upstream flight provider is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Booking is temporarily disabled by the operator (`booking_disabled`). Existing intents and refund requests are unaffected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/air/intents": {
      "post": {
        "tags": [
          "intents"
        ],
        "operationId": "createBookingIntent",
        "summary": "Create an escrow-backed booking intent from a selected offer.",
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        },
        "description": "Paid x402 endpoint. Send a valid `PAYMENT-SIGNATURE` header to create\nthe intent. Without payment, the API returns `402 Payment Required`.\n\nOptional request field referrer: an affiliate code (see POST /affiliates) — the resolved affiliate wallet is frozen on the intent and credited a share of the platform fee once the booking captures and the journey is flown without refund; unknown or self-referring codes are silently ignored.\n\nCreates the local booking intent and initializes its Solana escrow.\nThis does not fund the escrow, pay the airline, or issue a ticket.\n\n**Send an offer_id back EXACTLY as received.**",
        "security": [
          {
            "x402PaymentSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIntentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Booking intent created.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid wallet, request body, or payment signature.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "409": {
            "description": "Offer is unsupported or no longer usable, or an active intent already exists for this funding_wallet and offer_id (code `intent_already_exists`; the existing intent_id is returned in `detail.intent_id`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Escrow initialization or upstream provider failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Booking is temporarily disabled by the operator (`booking_disabled`). Existing intents and refund requests are unaffected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/air/intents/{intent_id}": {
      "get": {
        "tags": [
          "intents"
        ],
        "operationId": "getBookingIntent",
        "summary": "Fetch a booking intent by id.",
        "description": "Free. Poll it after /air/book: status moves to booked once the escrow is captured, and booking_reference carries the airline PNR as soon as the ticket is issued. A booking is finished for the traveller when booking_reference is present: relay it to them.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/IntentID"
          }
        ],
        "responses": {
          "200": {
            "description": "Booking intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Booking intent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/air/offer-details": {
      "post": {
        "summary": "Drill into one offer: every fare, bag prices, live price.",
        "description": "Paid x402 endpoint: $0.01 USDC (an offer from a browser-automation tier would cost $0.10, a real browser session at the supplier; none is on sale today). The PAYMENT-REQUIRED challenge always quotes the applicable price.\n\nRe-fetches the offer from the flight provider and returns it in the same shape as search results, with CURRENT price and expires_at, plus available_services: the purchasable extras (checked bags with weight limits and prices) on that exact fare. fare_options lists EVERY fare of this flight (same aircraft, every brand: Basic, Standard, Flex…), fresh from the supplier and price-ascending, each with its own bookable offer_id — including fares the search left out of its page. Pick the row you want and pass its offer_id to POST /air/intents.\n\nUse it to (1) answer \"how much is an extra bag on this fare?\" or \"is this fare refundable?\" — the ancillary/conditions questions search results cannot answer — and (2) revalidate a single offer minutes after a search, which is cheaper and quota-friendlier than re-searching.\n\nA stale or unknown offer_id returns 404 and the payment is never settled: refusals cost nothing. Offers expire roughly 20-30 minutes after search; on 404, re-search.\n\nServices are informational only: this API books the fare as-is and cannot add services to the order.",
        "operationId": "offerDetails",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OfferDetailsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Offer detail.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfferDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing offer_id or invalid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required: PAYMENT-REQUIRED header carries the x402 challenge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Offer unknown or expired — the payment is never settled. Re-search to get fresh offers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Upstream rate limited; Retry-After header set.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "x402PaymentSignature": []
          }
        ],
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01",
            "note": "always read the live PAYMENT-REQUIRED challenge"
          }
        }
      }
    },
    "/air/orders/{order_id}": {
      "get": {
        "tags": [
          "orders"
        ],
        "operationId": "getAirOrder",
        "summary": "Fetch airline order status.",
        "description": "Returns the booking reference and the airline order's status. If all you need is the PNR, GET /air/intents/{intent_id} carries it for free as booking_reference. Paid x402 endpoint at a token $0.01 USDC, and still gated by the X-Customer-Support-Code returned at intent creation. Refusals are never charged: a missing or wrong code (401/403) or an unknown order (404) happens before the payment settles. Note the response distinguishes an unknown order (404) from a wrong code (403).",
        "security": [
          {
            "x402PaymentSignature": [],
            "customerSupportCode": []
          }
        ],
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ord_0000000000000000000000",
            "description": "The airline order id (intent.order_id once booked)."
          }
        ],
        "responses": {
          "200": {
            "description": "Airline order status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required: PAYMENT-REQUIRED header carries the x402 challenge ($0.01).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "X-Customer-Support-Code header is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "X-Customer-Support-Code does not match this order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Order not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        }
      }
    },
    "/air/refund-requests": {
      "post": {
        "tags": [
          "intents"
        ],
        "operationId": "createRefundRequest",
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        },
        "summary": "Request a manual refund after the intent has been booked.",
        "description": "The intent id travels in the request body; the resource URL is static. Paid x402 endpoint. Send a valid `PAYMENT-SIGNATURE` header to record\nthe refund request. Without payment, the API returns `402 Payment Required`.\n\nRecords a refund request for a booked intent. The on-chain escrow has\nalready been captured by the time the intent is `booked`, so refunds at\nthis stage are processed manually by an operator. This endpoint persists\nthe request and pages the operator on Telegram; the response is\n`202 Accepted` and is **not** a guarantee of refund — eligibility and\nany applicable carrier penalties are reviewed manually.\n\nFor pre-capture states (`active`), the booking_sync worker handles\nrefunds automatically; this endpoint returns `409 use_automatic_refund`\nfor those.\n\nThe caller must include the `X-Customer-Support-Code` header matching\nthe code returned at intent creation.\n\n\nFor multi-passenger bookings, X-Passenger-Family-Name is the LEAD passenger's family name (position 0 of the /air/book list).",
        "security": [
          {
            "x402PaymentSignature": []
          }
        ],
        "parameters": [
          {
            "name": "X-Customer-Support-Code",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "BRIJ-K7MQ-T9RV",
            "description": "The customer_support_code returned when the intent was created."
          },
          {
            "name": "X-Passenger-Family-Name",
            "in": "header",
            "required": true,
            "description": "Family name of the passenger as captured at /book. Compared case-insensitively with leading/trailing whitespace trimmed.",
            "schema": {
              "type": "string"
            },
            "example": "Doe"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent_id",
                  "reason"
                ],
                "properties": {
                  "intent_id": {
                    "type": "string",
                    "description": "Id returned by POST /air/intents.",
                    "example": "intent_0000000000000000"
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Free-text explanation of why the refund is requested."
                  },
                  "contact": {
                    "type": "string",
                    "maxLength": 320,
                    "description": "Optional reply-to channel (email, phone, etc.) the operator can use to follow up."
                  }
                }
              },
              "example": {
                "intent_id": "intent_0000000000000000",
                "reason": "Passenger can no longer travel on these dates.",
                "contact": "jane.doe@example.com"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Refund request accepted and pending manual review.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "intent_id",
                    "requested_at",
                    "status"
                  ],
                  "properties": {
                    "intent_id": {
                      "type": "string"
                    },
                    "requested_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "received"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failure (missing or oversized reason, or invalid payment signature).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "X-Customer-Support-Code or X-Passenger-Family-Name header is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "X-Customer-Support-Code or X-Passenger-Family-Name does not match the intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Intent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Intent is not in a state that accepts a manual refund request (active intents are auto-refunded; already refunded; refund already requested; passenger family name unavailable).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/air/search": {
      "post": {
        "tags": [
          "flights"
        ],
        "operationId": "searchFlights",
        "summary": "Search live flight offers.",
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.10",
            "max": "5.00"
          }
        },
        "description": "Flight search can be paid with x402 or sponsored by the BRIJ gateway.\n\nFor direct x402 clients, send a valid `PAYMENT-SIGNATURE` header. Without\npayment, the API returns `402 Payment Required` carrying the **current** price.\n\nFor BRIJ Wallet preview calls, the gateway may send `X-BRIJ-SPONSORED-*`\nheaders. Providers should treat that as a BRIJ-sponsored preview, not as a\nuser-paid x402 settlement.\n\nEvery price in the response is the price a buyer pays: total_amount / total_amount_decimal (offers, fare_options, highlights) are all-in, and max_price filters on that figure. POST /air/intents asks exactly this amount as expected_escrow_amount (a wallet enrolled in a fee-waiving cohort is asked less, never more).\n\nBase x402 price is 0.10 USDC. The price is multiplied (up to 50×) by the\ncurrent search load: completed searches in the last 60 seconds and\nany upstream rate-limit response in the last 5 minutes. Always read\nthe latest `PAYMENT-REQUIRED` challenge before signing - the price\nyour client saw a moment ago may already be stale.\n\n\nThe same flight commonly appears several times at different prices: each offer is one fare (fare_brand_name, baggage, change/refund conditions) sold by one seller (owner_name). Two offers on the same flight can share identical conditions and differ only in seller and price — compare the fare fields, never assume cheaper means more restrictive.\n\n**Data boundaries — what this response does and does not contain.**\nEach offer carries EVERYTHING the flight inventory provider discloses at search time: itinerary (legs, times with IANA timezones, durations, aircraft, terminals, technical stops), identity (comparison_key, both carriers on codeshares, flight numbers, fare_basis_code), fare content (brand, cabin, included baggage, change/refund conditions with penalties), price breakdown (base + tax), CO2 estimate, and loyalty programmes. To drill into ONE offer — fresh price/expiry and paid-ancillary prices — use POST /air/offer-details. Filters (max_stops, departure_after/before, max_price) apply before sort, grouping and limit — so limit + sort=duration + max_stops=0 means \"the fastest directs\". Offers default to cheapest first; a full response can exceed 300 KB, so LLM-driven agents should send cheapest_per_itinerary=true with a limit and drill into finalists.\n\nNot available in SEARCH results (use POST /air/offer-details per offer):\n- Prices of paid ancillaries (extra checked bags and other extras).\n- Seat maps and specific seat availability.\n- Full legal fare-rule text. It does not exist upstream in machine form: the structured conditions object IS the complete machine-readable ruleset. For airline-side research, fare_basis_code plus the marketing carrier identifies the exact fare.\n\nEverywhere in this response, null/empty means the airline did not disclose the value — unknown, never zero or false.\n\n**Anti-pattern — truncation without grouping.** cheapest_per_itinerary=false combined with a small limit returns the N cheapest fare INSTANCES, not the N cheapest itineraries. Basic/Lite fares are always cheaper than Comfort/Flex/refundable/business variants of the SAME flight, so the pricier variants sort to the tail and fall off — and their absence from a truncated response proves nothing. To answer \"is there a refundable / with-bag / higher-cabin fare?\", always use cheapest_per_itinerary=true and read fare_options; it is lossless on price, brand, refund/change conditions and checked bags.\n\n**Progressive results.** The response may carry `status: enriching` plus a `search_id`: slower, cheaper fulfiller tiers are still quoting. Poll the free POST /air/search-updates with that `search_id` (every ~`poll_after_ms`) to receive their offers as they land, until `status: complete` — usually under 2 minutes. Do not choose an offer before then: the slower tiers often carry airlines the fast tier does not (other carriers' nonstops, notably) and cheaper fares. While enriching, the response also says this in words, in `next`.",
        "security": [
          {
            "x402PaymentSignature": []
          },
          {
            "brijSponsoredPreview": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "examples": {
                "madridToLisbon": {
                  "value": {
                    "origin_iata": "MAD",
                    "destination_iata": "LIS",
                    "depart_date": "2026-06-10",
                    "adults": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request or invalid payment signature.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "501": {
            "description": "Upstream flight provider is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/air/search-updates": {
      "post": {
        "tags": [
          "flights"
        ],
        "operationId": "searchUpdates",
        "summary": "Poll a progressive search for offers still arriving (free).",
        "description": "Free companion to POST /air/search — no x402 payment: the search was already paid, and the unguessable `search_id` is the authorization.\n\nA search answers within seconds with the fast tiers' offers and `status: enriching` when slower, cheaper fulfiller tiers are still working. Poll this endpoint (respecting `poll_after_ms`, ~5s) until `status: complete`. Each poll returns the full merged-and-deduplicated offer list so far — idempotent reads, safe to retry.\n\nThe `search_id` expires ~5 minutes after the search; after that this endpoint returns 410 and a new search is needed. The rest of the purchase tunnel (offer-details, intents, book) is unchanged — offers gained here are used exactly like offers from the initial response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchUpdatesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merged offers so far, plus progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchUpdatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed search_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown search_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "410": {
            "description": "This search_id has expired; run a new search.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "health"
        ],
        "operationId": "getHealth",
        "summary": "Check this API process is alive.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is alive.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/hotels/book": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Pay the hotel escrow and name the guests",
        "description": "Paid x402 endpoint: the intent's escrow amount. Body: intent_id, guests[] (the lead first, then at least one per room, each {given_name, family_name, born_on?}), email and phone_number (E.164) of the lead guest, optional special_requests (forwarded to the hotel). Every check (guests, price unchanged, nothing booked yet) happens before settle. Then the stay is booked at Duffel once the escrow is funded: poll POST /hotels/orders until status is confirmed (booking_reference set, escrow captured, confirmation emailed) or failed (refunded in full).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HotelBookRequest"
              },
              "example": {
                "intent_id": "intent_0000000000000000",
                "guests": [
                  {
                    "given_name": "Jane",
                    "family_name": "Doe"
                  }
                ],
                "email": "jane.doe@example.com",
                "phone_number": "+15551234567"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Booking running.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelBookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "6.00",
            "max": "5030.00",
            "note": "the price IS the intent's expected_escrow_amount: the all-in price of the stay, held in escrow, not a fee"
          }
        }
      }
    },
    "/hotels/cancel": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Cancel a hotel booking and file its refund",
        "description": "Paid x402 endpoint: $0.10 USDC. Body {intent_id}; headers X-Customer-Support-Code and X-Passenger-Family-Name (the lead guest's family name). Cancels at the hotel now. The refund is what the cancellation timeline returns at this moment, plus the service fee minus 2 % of the stay (between 2 and 5 USDC); it is sent to the refund wallet set at intent creation. A non-refundable rate returns only that part of the fee.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent_id"
                ],
                "properties": {
                  "intent_id": {
                    "type": "string",
                    "example": "intent_0000000000000000",
                    "description": "The intent id returned by POST /hotels/intents."
                  }
                }
              },
              "example": {
                "intent_id": "intent_0000000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelConfirmation"
                }
              }
            }
          },
          "401": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        },
        "parameters": [
          {
            "name": "X-Customer-Support-Code",
            "in": "header",
            "required": true,
            "description": "The customer_support_code returned when the intent was created.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Passenger-Family-Name",
            "in": "header",
            "required": true,
            "description": "The lead guest's family name (the first guest sent to POST /hotels/book).",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/hotels/intents": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Create the escrow for a quoted hotel stay",
        "description": "Paid x402 endpoint: $0.10 USDC. Identical to POST /air/intents with the offer_id from POST /hotels/quote. The escrow amount is the quote's ALL-IN total. Persist customer_support_code: it cannot be read again, and POST /hotels/orders and /hotels/cancel need it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIntentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Intent created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        }
      }
    },
    "/hotels/orders": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Get a hotel booking's status and reference",
        "description": "Paid x402 endpoint: $0.01 USDC. Body {intent_id}; header X-Customer-Support-Code. status awaiting_payment → booking → confirmed (booking_reference, escrow captured) | failed | cancelled | refunded; booking carries the full confirmation (hotel, dates, guests, key collection, cancellation terms).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent_id"
                ],
                "properties": {
                  "intent_id": {
                    "type": "string",
                    "example": "intent_0000000000000000",
                    "description": "The intent id returned by POST /hotels/intents."
                  }
                }
              },
              "example": {
                "intent_id": "intent_0000000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelOrder"
                }
              }
            }
          },
          "401": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        },
        "parameters": [
          {
            "name": "X-Customer-Support-Code",
            "in": "header",
            "required": true,
            "description": "The customer_support_code returned when the intent was created.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/hotels/places": {
      "get": {
        "tags": [
          "hotels"
        ],
        "summary": "Suggest cities and hotels by name for a hotel search",
        "description": "Free. Up to 8 cities matching q (2+ characters), each with an id to send as city_id to POST /hotels/search, and from 3 characters up to 8 hotels matching q by name (hotels[]: accommodation_id, name, address), each searched on its own with accommodation_id. Optional: /hotels/search also takes a typed location or coordinates.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Lisbon"
            },
            "description": "The start of a city name."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching cities.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "places": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "hotels": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "Hotels whose name matches q: accommodation_id, name, address, city, country."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/hotels/quote": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Lock one hotel rate and get its exact all-in price",
        "description": "Paid x402 endpoint: $0.01 USDC. Body {rate_id} from POST /hotels/rates. Answer: the stay as it will be booked (hotel, address, room, board, check-in/out dates and times, party, cancellation timeline, price with tax, fees, our service fee and what is due at the hotel) and offer_id (\"hotel:\u003cquote_id\u003e\"): pass it to POST /hotels/intents. Show the guest the price, what is due at the hotel and the cancellation terms before creating the intent. Refusals are free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rate_id"
                ],
                "properties": {
                  "rate_id": {
                    "type": "string",
                    "description": "rate_id from POST /hotels/rates, exactly as received."
                  }
                }
              },
              "example": {
                "rate_id": "rat_0000000000000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stay, quoted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelStay"
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        }
      }
    },
    "/hotels/rates": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "List the rooms and rates of one searched hotel",
        "description": "Paid x402 endpoint: $0.01 USDC. Body {hotel_id} from POST /hotels/search. Answer: room_types[], each with rates[]: rate_id (send it to POST /hotels/quote), board (room only, breakfast...), refundable, refundability and cancellation_timeline (what is refunded until when), price (hotel total with tax and fees, service fee, ALL-IN total, due at hotel). Rates paid at the hotel are not listed. Refusals are free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "hotel_id"
                ],
                "properties": {
                  "hotel_id": {
                    "type": "string",
                    "description": "hotel_id from POST /hotels/search, exactly as received."
                  }
                }
              },
              "example": {
                "hotel_id": "srr_0000000000000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rooms and rates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelRatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        }
      }
    },
    "/hotels/search": {
      "post": {
        "tags": [
          "hotels"
        ],
        "summary": "Search hotels for dates and a party in one city",
        "description": "Paid x402 endpoint: $0.10 USDC. Body: a place (city_id from GET /hotels/places, or one hotel by accommodation_id from its hotels[], or location as a city name, or latitude + longitude with radius_km), check_in_date and check_out_date (YYYY-MM-DD, up to 30 nights), rooms (1-4, default 1), adults (1-8, default 1), child_ages, free_cancellation_only, stars (e.g. [4, 5]), sort (price | price_desc). Answer: hotels[] cheapest first, each with hotel_id (send it to POST /hotels/rates), name, rating, address, price_from (the hotel's total for the whole stay), total_from (ALL-IN, USDC: + 5 USDC + 2 %, capped at 30) and due_at_hotel_from (paid at the hotel, on top: city tax, resort fees). Refusals are free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HotelSearchRequest"
              },
              "example": {
                "location": "Lisbon",
                "check_in_date": "2026-12-10",
                "check_out_date": "2026-12-12",
                "rooms": 1,
                "adults": 2
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hotels found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "health"
        ],
        "operationId": "getOpenAPI",
        "summary": "Fetch this OpenAPI document.",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": [
          "health"
        ],
        "operationId": "getReadiness",
        "summary": "Check database readiness.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service is not ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/close": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "End your sandbox lease now",
        "description": "Free. Archives your transcript, destroys the machine and closes the browser. Copy out what you need first: nothing survives. Unused minutes are not refunded.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease_token"
                ],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ok, lease_id, status: closed}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "description": "Closed."
                    },
                    "lease_id": {
                      "description": "The lease."
                    },
                    "status": {
                      "description": "closed."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "410": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/exec": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Run a shell command in your sandbox",
        "description": "Free (the lease is paid). Runs cmd with bash in /workspace. Foreground: up to 60 s, answers stdout (≤1 MiB), stderr (≤256 KiB), exit_code; past the timeout: exit_code 124, timed_out. background: true starts it detached (up to the lease's end) and answers process_id + log: read it with POST /sandbox/logs. Multi-line scripts and heredocs are fine.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease_token",
                  "cmd"
                ],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  },
                  "cmd": {
                    "type": "string",
                    "description": "Shell command(s), ≤64 KiB.",
                    "example": "python3 -c 'print(2+2)'"
                  },
                  "background": {
                    "type": "boolean",
                    "description": "Run detached; poll POST /sandbox/logs."
                  },
                  "timeout_s": {
                    "type": "integer",
                    "description": "Foreground ≤60 (default 30); background ≤ the lease's remaining time."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ok, exit_code, stdout, stderr, timed_out?, duration_ms} or {background, process_id, log}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "description": "The sandbox answered."
                    },
                    "exit_code": {
                      "description": "The command's exit code (124: timed out)."
                    },
                    "stdout": {
                      "description": "Standard output, ≤1 MiB."
                    },
                    "stderr": {
                      "description": "Standard error, ≤256 KiB."
                    },
                    "timed_out": {
                      "description": "True when the foreground limit cut it."
                    },
                    "background": {
                      "description": "True for a detached command."
                    },
                    "process_id": {
                      "description": "Detached command's id, for /sandbox/logs."
                    },
                    "log": {
                      "description": "Detached command's log path, for /sandbox/logs."
                    },
                    "duration_ms": {
                      "description": "Run time."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "410": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/extend": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Add paid minutes to your open sandbox lease",
        "description": "Paid x402 endpoint: $0.03 USDC per minute, like POST /sandbox/start (never waived over MCP). minutes 1 to 60 (one-minute steps: keep a machine open while your owner chats and pay for what you use), a lease is at most 120 minutes in total. Checked before payment (409 lease_too_long, 410 lease_ended); the clock moves only once the payment settled.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease_token",
                  "minutes"
                ],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  },
                  "minutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 60,
                    "description": "Minutes to add. Price = minutes × 0.03 USDC."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ok, lease_id, minutes (total), expires_at}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "description": "Extended."
                    },
                    "lease_id": {
                      "description": "The lease."
                    },
                    "minutes": {
                      "description": "The lease's total minutes now."
                    },
                    "expires_at": {
                      "description": "The new end."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "410": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/files": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Read, write or list files in your sandbox",
        "description": "Free. Paths are relative to /workspace and may not leave it. op=list: entries two levels deep. op=read: ≤512 KiB per call as content_b64, from offset; repeat with next_offset until eof. op=write: content_b64 (≤ ~700 KiB per call; append: true to add chunks).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease_token",
                  "op"
                ],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  },
                  "op": {
                    "type": "string",
                    "enum": [
                      "list",
                      "read",
                      "write"
                    ],
                    "description": "list, read or write."
                  },
                  "path": {
                    "type": "string",
                    "example": "results/out.csv",
                    "description": "Relative to /workspace (\"\" = /workspace itself)."
                  },
                  "content_b64": {
                    "type": "string",
                    "description": "op=write: the bytes, base64."
                  },
                  "offset": {
                    "type": "integer",
                    "description": "op=read: byte offset to read from (next_offset of the previous call)."
                  },
                  "append": {
                    "type": "boolean",
                    "description": "op=write: append instead of replacing (to send a large file in chunks)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "list: {entries}; read: {size, content_b64, next_offset, eof}; write: {size}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "description": "op=list: [{type, size, path}]."
                    },
                    "size": {
                      "description": "op=read: file size; op=write: size after writing."
                    },
                    "content_b64": {
                      "description": "op=read: the chunk, base64."
                    },
                    "next_offset": {
                      "description": "op=read: offset for the next chunk."
                    },
                    "eof": {
                      "description": "op=read: true when the file is fully read."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "410": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/history": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Read a lease's timeline (commands, transcript)",
        "description": "Free. By lease_token or the view_token in view_url, during the lease and for 7 days after it: every command with its output (secrets masked), files written, the transcript the agent wrote with brij-log, start and close. What view_url shows, as JSON. Long-poll mode (any of after_event / transcript_offset / wait_s): answers {status, events (new ones), last_event, transcript (new brij-log lines, live while the lease runs), transcript_offset} as soon as something is new, or after wait_s: call it in a loop to stream an agent's steps. Live agent steps arrive in `transcript` (new brij-log lines, JSONL), not in `events`: `events` holds what BRIJ records (commands, files, start/close) and gets the transcript only once, archived at close.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  },
                  "view_token": {
                    "type": "string",
                    "description": "The t= value of view_url."
                  },
                  "after_event": {
                    "type": "integer",
                    "description": "Long-poll: answer only events with id \u003e after_event (0 the first time; then last_event of the previous answer)."
                  },
                  "transcript_offset": {
                    "type": "integer",
                    "description": "Long-poll: byte offset in the live transcript (0 first; then transcript_offset of the previous answer)."
                  },
                  "wait_s": {
                    "type": "integer",
                    "description": "Long-poll: wait up to this many seconds (≤25) for something new."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{lease_id, status, minutes, paid_usdc, expires_at, closed_at?, live_view_url?, events}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lease_id": {
                      "description": "The lease."
                    },
                    "status": {
                      "description": "starting, running or closed."
                    },
                    "minutes": {
                      "description": "Paid minutes."
                    },
                    "paid_usdc": {
                      "description": "What was paid."
                    },
                    "expires_at": {
                      "description": "End of the lease."
                    },
                    "closed_at": {
                      "description": "When it ended."
                    },
                    "close_reason": {
                      "description": "closed_by_agent, expired, …"
                    },
                    "live_view_url": {
                      "description": "While running: watch the browser."
                    },
                    "events": {
                      "description": "Timeline: [{at, kind, detail}] — start, exec, file_write, transcript, close."
                    },
                    "last_event": {
                      "description": "Long-poll: the id to send as after_event next."
                    },
                    "transcript": {
                      "description": "Long-poll: new transcript lines (JSONL, one per brij-log call)."
                    },
                    "transcript_offset": {
                      "description": "Long-poll: the offset to send next."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/logs": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Read a background command's status and output",
        "description": "Free. Answers status (running|completed|failed|gone), exit_code, chunk_b64 (≤256 KiB of the log from offset, base64) and next_offset: call again with next_offset until completed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease_token",
                  "log"
                ],
                "properties": {
                  "lease_token": {
                    "type": "string",
                    "description": "The lease_token returned by POST /sandbox/start (shown once). Also accepted as Authorization: Bearer.",
                    "example": "sbt_000000000000000000000000000000000000000000000000"
                  },
                  "process_id": {
                    "type": "string",
                    "description": "The process_id POST /sandbox/exec returned (for the status)."
                  },
                  "log": {
                    "type": "string",
                    "description": "The log path POST /sandbox/exec returned."
                  },
                  "offset": {
                    "type": "integer",
                    "description": "Byte offset; 0 first."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{status, exit_code, chunk_b64, next_offset}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "description": "running, completed, failed or gone."
                    },
                    "exit_code": {
                      "description": "Exit code once finished."
                    },
                    "chunk_b64": {
                      "description": "Up to 256 KiB of the log from offset, base64."
                    },
                    "next_offset": {
                      "description": "Offset for the next call."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "410": {
            "description": "Refused. 401: unknown lease_token. 410: the lease has ended. Body: {code, message}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/start": {
      "post": {
        "tags": [
          "sandbox"
        ],
        "summary": "Rent a Linux computer + browser for N minutes",
        "description": "Paid x402 endpoint: $0.03 USDC per minute, browser included, 5 to 60 minutes, paid once up front (minutes × 0.03, e.g. 15 minutes = 0.45 USDC). Over MCP too: this is a sale, not a toll, so it is NEVER waived — retry the tool with the payment. Opens a disposable Ubuntu machine (1 vCPU, 3 GB RAM, 4 GB disk; node 22, python 3, git, curl, jq, playwright clients) and a separate Browserbase browser already connected to it: inside, connect with playwright connectOverCDP(process.env.BROWSER_WS_URL). Optional env: your own variables (a model API key, an MCP token…), passed to every command, masked in your owner's log. No model is included: `minirouter-signup` inside opens your own pay-as-you-go account. Answers lease_token (KEEP IT: shown once, every other call needs it), view_url (give it to your owner: every command, the browser live, your transcript written with `brij-log`), expires_at. One open lease per wallet; refused before payment when the service is full (503 sandbox_capacity) or disabled. Unused minutes are not refunded. With home_id, the machine keeps its /workspace between leases (rent per task, keep the state). Everything in the machine is destroyed at the end. Rules: no captcha solving or anti-bot evasion, no abuse of third parties; a breach ends the lease and blocks the wallet.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "minutes"
                ],
                "properties": {
                  "minutes": {
                    "type": "integer",
                    "minimum": 5,
                    "maximum": 60,
                    "description": "Lease length. Price = minutes × 0.03 USDC.",
                    "example": 15
                  },
                  "env": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Optional: your own environment variables for every command (≤32, ≤32 KiB). Names starting with BRIJ_ and BROWSER_WS_URL are reserved.",
                    "example": {
                      "MY_API_KEY": "…"
                    }
                  },
                  "home_id": {
                    "type": "string",
                    "description": "Optional persistent home (your agent id, [A-Za-z0-9_-], ≤64). The first lease with an unknown home_id creates it and binds it to the paying wallet; every later lease with it restores /workspace (your files, your runner, .brij/minirouter.json…) before you get the machine, and the lease's end saves it again (encrypted, ≤100 MB compressed, kept 30 days after last use). One open lease per home. Env variables are NOT saved: pass them at each start.",
                    "example": "my-agent-01"
                  },
                  "init": {
                    "type": "string",
                    "description": "Optional command started in the background once the lease is paid, after the home is restored, with your env (e.g. `python3 runner.py`). The answer's init says whether it started, with its process_id and log for POST /sandbox/logs."
                  },
                  "voucher": {
                    "type": "string",
                    "description": "Optional test voucher an operator gave you: the lease is free and no payment is asked."
                  }
                }
              },
              "example": {
                "minutes": 15
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lease open. {lease_id, lease_token, view_url, minutes, expires_at, live_view_url, next}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lease_id": {
                      "description": "The lease's public id."
                    },
                    "lease_token": {
                      "description": "Bearer for every other sandbox call. Shown once: keep it."
                    },
                    "view_url": {
                      "description": "Read-only page for your owner: commands, live browser, transcript."
                    },
                    "minutes": {
                      "description": "Paid minutes."
                    },
                    "expires_at": {
                      "description": "When the machine is destroyed."
                    },
                    "live_view_url": {
                      "description": "Watch the browser live while the lease runs."
                    },
                    "next": {
                      "description": "What to do next, in words."
                    },
                    "home": {
                      "description": "With home_id: {home_id, restored}."
                    },
                    "init": {
                      "description": "With init: {started, process_id, log} or {started: false, error}."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/shopcom/buy": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Pay a Shop order's escrow; BRIJ buys at the store",
        "description": "Pays the intent's escrow with x402 (amount = expected_escrow_amount, payTo = the intent's escrow), like POST /air/book; a wallet that cannot sign x402 may instead send expected_escrow_amount USDC to the intent's vault_address and then call this: a funded vault buys with no second payment. BRIJ then loads its card, completes the store's checkout through Shop and captures the escrow once the store confirms the order; if the store cannot be paid, the escrow refunds in full. Answer: the order (status awaiting_payment, buying, ordered or failed). Poll POST /shopcom/orders.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent_id"
                ],
                "properties": {
                  "intent_id": {
                    "type": "string",
                    "description": "From POST /shopcom/intents."
                  }
                }
              },
              "example": {
                "intent_id": "intent_0000000000000000"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Paid (or already funded): the order is queued; poll POST /shopcom/orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intent_id": {
                      "type": "string",
                      "description": "The intent."
                    },
                    "status": {
                      "type": "string",
                      "description": "awaiting_payment, buying, ordered or failed (refunded in full)."
                    },
                    "shop": {
                      "type": "string",
                      "description": "The store's domain."
                    },
                    "title": {
                      "type": "string",
                      "description": "The item."
                    },
                    "quantity": {
                      "type": "integer",
                      "description": "Units."
                    },
                    "ship_to": {
                      "type": "object",
                      "description": "The recipient, as it will be shipped."
                    },
                    "merchant": {
                      "type": "object",
                      "description": "The store's own figures, in its currency.",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "description": "ISO 4217."
                        },
                        "subtotal": {
                          "type": "string",
                          "description": "Items."
                        },
                        "discount": {
                          "type": "string",
                          "description": "Discounts the store applied (negative)."
                        },
                        "shipping": {
                          "type": "string",
                          "description": "Shipping."
                        },
                        "tax": {
                          "type": "string",
                          "description": "Tax."
                        },
                        "total": {
                          "type": "string",
                          "description": "What the store charges."
                        }
                      }
                    },
                    "paid_usdc": {
                      "type": "string",
                      "description": "The escrow amount."
                    },
                    "merchant_order": {
                      "type": "string",
                      "description": "The store's order number, once ordered."
                    },
                    "message": {
                      "type": "string",
                      "description": "The status in words."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "6.00",
            "max": "5030.00",
            "note": "the price IS the intent's expected_escrow_amount: the all-in price of the stay, held in escrow, not a fee"
          }
        }
      }
    },
    "/shopcom/intents": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Lock a Shop quote in an escrow",
        "description": "Paid x402 endpoint: $0.10 USDC. Identical to POST /air/intents with the offer_id from POST /shopcom/quote. The escrow amount is the quote's ALL-IN total_usdc. Persist customer_support_code: it cannot be read again, and POST /shopcom/orders and refund requests need it. During the beta only invited wallets can create one (403 shopcom_beta_only).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIntentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Intent created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.10"
          }
        }
      }
    },
    "/shopcom/orders": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Shop order status",
        "description": "Paid x402 endpoint: $0.01 USDC. The order of a Shop intent: status (awaiting_payment, buying, ordered, failed), the store's figures, what was paid and the store's order number once ordered. Needs the X-Customer-Support-Code returned at intent creation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent_id"
                ],
                "properties": {
                  "intent_id": {
                    "type": "string",
                    "example": "intent_0000000000000000",
                    "description": "The intent id returned by POST /hotels/intents."
                  }
                }
              },
              "example": {
                "intent_id": "intent_0000000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intent_id": {
                      "type": "string",
                      "description": "The intent."
                    },
                    "status": {
                      "type": "string",
                      "description": "awaiting_payment, buying, ordered or failed (refunded in full)."
                    },
                    "shop": {
                      "type": "string",
                      "description": "The store's domain."
                    },
                    "title": {
                      "type": "string",
                      "description": "The item."
                    },
                    "quantity": {
                      "type": "integer",
                      "description": "Units."
                    },
                    "ship_to": {
                      "type": "object",
                      "description": "The recipient, as it will be shipped."
                    },
                    "merchant": {
                      "type": "object",
                      "description": "The store's own figures, in its currency.",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "description": "ISO 4217."
                        },
                        "subtotal": {
                          "type": "string",
                          "description": "Items."
                        },
                        "discount": {
                          "type": "string",
                          "description": "Discounts the store applied (negative)."
                        },
                        "shipping": {
                          "type": "string",
                          "description": "Shipping."
                        },
                        "tax": {
                          "type": "string",
                          "description": "Tax."
                        },
                        "total": {
                          "type": "string",
                          "description": "What the store charges."
                        }
                      }
                    },
                    "paid_usdc": {
                      "type": "string",
                      "description": "The escrow amount."
                    },
                    "merchant_order": {
                      "type": "string",
                      "description": "The store's order number, once ordered."
                    },
                    "message": {
                      "type": "string",
                      "description": "The status in words."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-payment-info": {
          "protocols": [
            "x402"
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        },
        "parameters": [
          {
            "name": "X-Customer-Support-Code",
            "in": "header",
            "required": true,
            "description": "The customer_support_code returned when the intent was created.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/shopcom/product": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Read one Shop product",
        "description": "Paid x402 endpoint: $0.01 USDC. One product from Shop's catalog (id gid://shopify/p/… from POST /shopcom/search, or a store's product URL) with every variant, its price and seller, relayed untouched.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Shop product id or product URL."
                  },
                  "ships_to": {
                    "type": "string",
                    "description": "Destination country, ISO alpha-2 (default US)."
                  }
                }
              },
              "example": {
                "id": "gid://shopify/p/0000000000000000000000",
                "ships_to": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shop's product answer, relayed untouched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product": {
                      "type": "object",
                      "description": "The product with every variant (id, options, price, availability, seller)."
                    },
                    "products": {
                      "type": "array",
                      "description": "For a product URL: the matching products.",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "422": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "502": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/shopcom/quote": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Quote a Shop purchase to an address",
        "description": "Paid x402 endpoint: $0.01 USDC. Opens a real checkout at the store through Shop, shipped to ship_to, and prices it in USDC: the store's total (items, shipping, tax, converted at the day's rate plus a margin when the store does not charge USD) + BRIJ's fee. Answer: offer_id (\"shopcom:\u003cquote\u003e\"), the store's figures, total_usdc, expires_at (about 20 minutes). Stores whose checkout carries an add-on are quoted too (BRIJ approves the payment as the account holder); a store whose checkout needs something else (a check Shop cannot pass for an agent) answers 409 not_agent_ready (look for the same item at another seller). Show the buyer the item, the store, the address and total_usdc before creating the intent. Refusals are free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ship_to"
                ],
                "properties": {
                  "shop": {
                    "type": "string",
                    "description": "The seller's domain from the catalog (seller.url without https://), e.g. adamsfootwear.com."
                  },
                  "variant_id": {
                    "type": "string",
                    "description": "Variant id from the catalog (gid://shopify/ProductVariant/… or its number)."
                  },
                  "product_url": {
                    "type": "string",
                    "description": "Instead of shop + variant_id: the product's URL (single-variant products only)."
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "1-5, default 1."
                  },
                  "ship_to": {
                    "type": "object",
                    "required": [
                      "first_name",
                      "last_name",
                      "street_address",
                      "city",
                      "postal_code",
                      "country",
                      "phone"
                    ],
                    "properties": {
                      "first_name": {
                        "type": "string",
                        "description": "Recipient's first name."
                      },
                      "last_name": {
                        "type": "string",
                        "description": "Also the family name a refund request is authenticated with."
                      },
                      "street_address": {
                        "type": "string",
                        "description": "Street and number."
                      },
                      "extended_address": {
                        "type": "string",
                        "description": "Apartment, suite (optional)."
                      },
                      "city": {
                        "type": "string",
                        "description": "City."
                      },
                      "region": {
                        "type": "string",
                        "description": "State or province code when the country has them, e.g. NY."
                      },
                      "postal_code": {
                        "type": "string",
                        "description": "Postal / ZIP code."
                      },
                      "country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2, e.g. US."
                      },
                      "phone": {
                        "type": "string",
                        "description": "Recipient phone in E.164, e.g. +12125551234 (stores require it for delivery)."
                      }
                    },
                    "description": "Who receives the parcel. Ask the buyer for each field."
                  }
                }
              },
              "example": {
                "shop": "example-store.com",
                "variant_id": "gid://shopify/ProductVariant/1",
                "quantity": 1,
                "ship_to": {
                  "first_name": "Ada",
                  "last_name": "Lovelace",
                  "street_address": "350 5th Avenue",
                  "city": "New York",
                  "region": "NY",
                  "postal_code": "10118",
                  "country": "US",
                  "phone": "+12125551234"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The purchase, priced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offer_id": {
                      "type": "string",
                      "description": "\"shopcom:\u003cquote\u003e\": pass it to POST /shopcom/intents exactly as received."
                    },
                    "shop": {
                      "type": "string",
                      "description": "The store's domain."
                    },
                    "title": {
                      "type": "string",
                      "description": "The item as the store names it."
                    },
                    "quantity": {
                      "type": "integer",
                      "description": "Units."
                    },
                    "ship_to": {
                      "type": "object",
                      "description": "The recipient, as it will be shipped."
                    },
                    "merchant": {
                      "type": "object",
                      "description": "The store's own figures, in its currency.",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "description": "ISO 4217."
                        },
                        "subtotal": {
                          "type": "string",
                          "description": "Items."
                        },
                        "discount": {
                          "type": "string",
                          "description": "Discounts the store applied (negative)."
                        },
                        "shipping": {
                          "type": "string",
                          "description": "Shipping."
                        },
                        "tax": {
                          "type": "string",
                          "description": "Tax."
                        },
                        "total": {
                          "type": "string",
                          "description": "What the store charges."
                        }
                      }
                    },
                    "merchant_usd": {
                      "type": "string",
                      "description": "The store's total in USD (converted at the day's rate plus a margin off USD)."
                    },
                    "fee_usdc": {
                      "type": "string",
                      "description": "BRIJ's fee."
                    },
                    "total_usdc": {
                      "type": "string",
                      "description": "All-in: what the escrow will hold."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Create the intent before this."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "422": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "502": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/shopcom/search": {
      "post": {
        "tags": [
          "shopcom"
        ],
        "summary": "Search Shop's catalog",
        "description": "Paid x402 endpoint: $0.01 USDC. Shop's own catalog search (millions of Shopify stores), relayed untouched: products with their variants, prices, sellers (seller.url is the store's domain) and variant ids. Pass a variant id and its seller's domain to POST /shopcom/quote.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "What to look for, in the buyer's words."
                  },
                  "ships_to": {
                    "type": "string",
                    "description": "Destination country, ISO alpha-2 (default US)."
                  },
                  "currency": {
                    "type": "string",
                    "description": "Preferred currency for prices and max_price_minor, e.g. USD."
                  },
                  "max_price_minor": {
                    "type": "integer",
                    "description": "Price ceiling in minor units of currency (2000 = 20.00)."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "1-20, default 10."
                  }
                }
              },
              "example": {
                "query": "wool socks",
                "ships_to": "US",
                "currency": "USD",
                "max_price_minor": 2000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shop's catalog answer, relayed untouched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "description": "Shop's products, each with variants (id, title, price {amount minor units, currency}, seller {name, url}).",
                      "items": {
                        "type": "object"
                      }
                    },
                    "messages": {
                      "type": "array",
                      "description": "Shop's notes on the search (filters applied, conversions).",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "422": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "502": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Refusal — never settled, nothing charged. Body: {code, message, detail?}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required or payment verification failed.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://travel.brij.fi"
    }
  ],
  "tags": [
    {
      "name": "health"
    },
    {
      "name": "flights"
    },
    {
      "name": "intents"
    },
    {
      "name": "orders"
    },
    {
      "description": "Book hotel stays worldwide (Duffel Stays inventory, USD). Search → rates → quote → intent (escrow) → book (guests) → orders, cancel. The booking is made at Duffel as soon as the escrow is funded and confirmed in the same call; a refused booking refunds in full automatically.",
      "name": "hotels"
    },
    {
      "description": "Rent a disposable Linux computer with a browser already running, by the minute, over x402. You run commands and files in it; the browser is a separate machine you drive from inside with Playwright (BROWSER_WS_URL). Bring your own model and keys. Your owner watches every command, the browser live and your transcript on view_url.",
      "name": "sandbox"
    },
    {
      "description": "Shop (shop.com): buy from Shopify stores with USDC. Search Shop's catalog, quote a real checkout to an address, pay the escrow; BRIJ buys and pays the store.",
      "name": "shopcom"
    }
  ]
}