{"openapi":"3.1.0","info":{"title":"Fresh Kosher Cruises public information API","version":"1.0.0","description":"Anonymous, read-only research and planning quotes from published exports. No customer records, reservations, holds, payments or provider scrapes. Prices are USD; ages are at departure. See /developers/ for interpretation and examples."},"servers":[{"url":"https://freshkosher.cruises"},{"url":"https://fkc.tvlmgnt.com","description":"Development"}],"externalDocs":{"url":"https://freshkosher.cruises/developers/"},"paths":{"/sailing-data/search.json":{"get":{"operationId":"search_sailings","summary":"Find kosher cruise sailings","description":"Search published upcoming departures by dates, destination, line, port, duration and kosher program. Search is a catalog listing; cabin availability and prices are checked by get_sailing or calculate_quote.","security":[],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Words matched against ship, destination, region, departure port and cruise line. All words must match; omit conversational filler."}},{"name":"cruiseLine","in":"query","required":false,"schema":{"type":"string","enum":["royal-caribbean","norwegian","princess","oceania"]}},{"name":"destination","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Destination or region substring, e.g. Alaska or Caribbean."}},{"name":"departurePort","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Inclusive departure date (YYYY-MM-DD)."}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Inclusive departure date (YYYY-MM-DD)."}},{"name":"minNights","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"maxNights","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"program","in":"query","required":false,"schema":{"type":"string","enum":["included","optional","waitlist","minyan"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Public data; inspect the business status and expiry before quoting a price.","content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"const":1},"sourceUrl":{"type":"string","format":"uri"},"retrievedAt":{"type":"string","format":"date-time"},"total":{"type":"integer","minimum":0},"offset":{"type":"integer"},"limit":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"availabilityNote":{"type":"string"},"sailings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"ship":{"type":"string"},"cruiseLine":{"type":"string"},"cruiseLineSlug":{"type":"string","enum":["royal-caribbean","norwegian","princess","oceania"]},"departureDate":{"type":"string","format":"date"},"nights":{"type":"integer"},"destination":{"type":"string"},"region":{"type":"string"},"departurePort":{"type":"string"},"program":{"type":"string","enum":["included","optional","waitlist","minyan"]},"adultsOnly":{"type":"boolean"},"cabinAvailability":{"const":"not_checked"},"detailsUrl":{"type":"string","format":"uri"},"quoteUrl":{"type":"string","format":"uri"}},"required":["id","url","ship","departureDate","nights","program","cabinAvailability"]}}},"required":["schemaVersion","sourceUrl","retrievedAt","total","offset","limit","nextOffset","availabilityNote","sailings"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Published sailing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported party or ages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached. Retry after the Retry-After header.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Public source temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sailing-data/{sailingId}.json":{"get":{"operationId":"get_sailing","summary":"Get sailing details and current fares","description":"Get a published sailing, itinerary, supervision, dining rules and verified current cabin prices for an exact occupancy (1–4 guests). Missing/stale prices do not mean sold out. Child ages are required for a complete age-based dining quote.","security":[],"parameters":[{"name":"sailingId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$","description":"Published sailing ID returned by search_sailings."}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":4,"default":2}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3,"default":0}}],"responses":{"200":{"description":"Public data; inspect the business status and expiry before quoting a price.","content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"const":1},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"ship":{"type":"string"},"departureDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"nights":{"type":"integer"},"program":{"type":"string","enum":["included","optional","waitlist","minyan"]},"adultsOnly":{"type":"boolean"},"diningRates":{"type":["object","null"]},"diningTotal":{"type":["number","null"],"minimum":0},"retrievedAt":{"type":"string","format":"date-time"},"diningDescription":{"type":"string"},"supervisionOrganization":{"type":"string"},"itineraryStatus":{"enum":["published","unavailable"]},"itinerary":{"type":"array","items":{"type":"object","properties":{"day":{"type":"integer"},"date":{"type":"string","format":"date"},"port":{"type":"string"},"time":{"type":"string"},"description":{"type":"string"}},"required":["day","date","port","time","description"]}},"pricing":{"type":"object","properties":{"currency":{"const":"USD"},"adults":{"type":"integer"},"children":{"type":"integer"},"status":{"enum":["available","sold_out","unavailable","stale","archived"]},"basis":{"type":"string"},"generatedAt":{"type":["string","null"],"format":"date-time"},"inventoryUpdated":{"type":["string","null"],"format":"date-time"},"validThrough":{"type":["string","null"],"format":"date-time"},"sourceUrl":{"type":["string","null"],"format":"uri"},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"categoryCode":{"type":"string"},"cabinCode":{"type":"string"},"cabinName":{"type":"string"},"cruisePerPerson":{"type":"number","minimum":0},"cruiseTotal":{"type":"number","minimum":0},"sourceUpdated":{"type":"string","format":"date-time"},"validThrough":{"type":"string","format":"date-time"},"withKosherTotal":{"type":["number","null"],"minimum":0}},"required":["cruisePerPerson","cruiseTotal","withKosherTotal","sourceUpdated","validThrough"]}}},"required":["currency","adults","children","status","basis","generatedAt","inventoryUpdated","validThrough","sourceUrl","categories"]}},"required":["schemaVersion","id","url","ship","departureDate","endDate","nights","program","adultsOnly","diningRates","diningTotal","retrievedAt","diningDescription","supervisionOrganization","itineraryStatus","itinerary","pricing"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Published sailing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported party or ages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached. Retry after the Retry-After header.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Public source temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sailing-data/{sailingId}/quote.json":{"get":{"operationId":"calculate_quote","summary":"Calculate a party planning quote","description":"Calculate cruise and dining totals for the supplied ages at departure in ONE cabin. Uses exact exported occupancy with fresh evidence. Returns dated planning estimates, never holds or bookings. Waitlisted or unoffered Fresh Kosher dining never becomes an available combined quote. Cruise-line child promotions and age policies must be revalidated.","security":[],"parameters":[{"name":"sailingId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$","description":"Published sailing ID returned by search_sailings."}},{"name":"ages","in":"query","required":true,"schema":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"integer","minimum":0,"maximum":120},"description":"Age at departure for every guest in ONE cabin. At least one guest must be 13+. Oceania Fresh Kosher groups require every guest to be 18+."},"style":"form","explode":false},{"name":"dining","in":"query","required":false,"schema":{"type":"string","enum":["fresh","cruise_only"],"default":"fresh","description":"Choose fresh for a combined Fresh Kosher planning quote. Inclusive fares retain included dining even if cruise_only is requested."}},{"name":"categoryCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z0-9]{1,5}$","description":"Optional exact category code from get_sailing. Returns its lowest verified current cabin fare."}}],"responses":{"200":{"description":"Public data; inspect the business status and expiry before quoting a price.","content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"const":1},"sourceUrl":{"type":"string","format":"uri"},"retrievedAt":{"type":"string","format":"date-time"},"sailingId":{"type":"string"},"ship":{"type":"string"},"departureDate":{"type":"string","format":"date"},"currency":{"const":"USD"},"status":{"enum":["available","sold_out","unavailable","stale","archived","category_unavailable","dining_waitlist","fresh_dining_not_offered","dining_rates_unavailable"]},"estimateOnly":{"const":true},"party":{"type":"object","properties":{"agesAtDeparture":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"integer","minimum":0,"maximum":120},"description":"Age at departure for every guest in ONE cabin. At least one guest must be 13+. Oceania Fresh Kosher groups require every guest to be 18+."},"adults":{"type":"integer"},"children":{"type":"integer"},"cabins":{"const":1}},"required":["agesAtDeparture","adults","children","cabins"]},"program":{"type":"string","enum":["included","optional","waitlist","minyan"]},"dining":{"type":"object","properties":{"requested":{"type":"string","enum":["fresh","cruise_only"],"default":"fresh","description":"Choose fresh for a combined Fresh Kosher planning quote. Inclusive fares retain included dining even if cruise_only is requested."},"status":{"enum":["included","not_selected","waitlist","not_offered","available","unavailable"]},"includedInCruiseFare":{"type":"boolean"},"charges":{"type":"array","items":{"type":"object","properties":{"ageBand":{"type":"string"},"count":{"type":"integer"},"perGuestForSailing":{"type":["number","null"],"minimum":0},"subtotal":{"type":["number","null"],"minimum":0}},"required":["ageBand","count","perGuestForSailing","subtotal"]}},"subtotal":{"type":["number","null"],"minimum":0},"gratuityRate":{"type":["number","null"],"minimum":0},"gratuity":{"type":["number","null"],"minimum":0},"roundingAdjustment":{"type":["number","null"]},"total":{"type":["number","null"],"minimum":0}},"required":["requested","status","includedInCruiseFare","charges","subtotal","gratuityRate","gratuity","roundingAdjustment","total"]},"pricingStatus":{"type":"string"},"pricingSourceUrl":{"type":["string","null"],"format":"uri"},"feedGeneratedAt":{"type":["string","null"],"format":"date-time"},"validThrough":{"type":["string","null"],"format":"date-time"},"options":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"categoryCode":{"type":"string"},"cabinCode":{"type":"string"},"cabinName":{"type":"string"},"cruisePerPerson":{"type":"number","minimum":0},"cruiseTotal":{"type":"number","minimum":0},"sourceUpdated":{"type":"string","format":"date-time"},"validThrough":{"type":"string","format":"date-time"},"diningTotal":{"type":["number","null"],"minimum":0},"total":{"type":["number","null"],"minimum":0}},"required":["cruisePerPerson","cruiseTotal","sourceUpdated","validThrough","diningTotal","total"]}},"assumptions":{"type":"array","items":{"type":"string"}},"termsUrl":{"type":"string","format":"uri"}},"required":["schemaVersion","sourceUrl","retrievedAt","sailingId","ship","departureDate","currency","status","estimateOnly","party","program","dining","pricingStatus","pricingSourceUrl","feedGeneratedAt","validThrough","options","assumptions","termsUrl"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Published sailing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported party or ages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached. Retry after the Retry-After header.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Public source temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sailing-data/policies.json":{"get":{"operationId":"get_policies","summary":"Read public program and booking guidance","description":"Read published Fresh Kosher guidance with source links. Individual sailing terms and dining arrangements take precedence.","security":[],"parameters":[{"name":"topic","in":"query","required":false,"schema":{"type":"string","enum":["all","pricing","dining","children","booking","minyan"],"default":"all"}}],"responses":{"200":{"description":"Public data; inspect the business status and expiry before quoting a price.","content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"const":1},"sourceUrl":{"type":"string","format":"uri"},"guidanceUpdated":{"type":"string","format":"date"},"termsUrl":{"type":"string","format":"uri"},"note":{"type":"string"},"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"topic":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"}},"required":["id","topic","question","answer","sourceUrl"]}}},"required":["schemaVersion","sourceUrl","guidanceUpdated","termsUrl","note","policies"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Published sailing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported party or ages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached. Retry after the Retry-After header.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Public source temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}