{"openapi":"3.1.0","info":{"title":"WedStay API","version":"1.0.0","description":"Search wedding venues and vendors with real pricing. The first open wedding venue API. WedStay provides structured data on wedding venues and vendors across the US — including pricing that most venues hide.","contact":{"name":"WedStay","url":"https://www.thewedstay.com/developers"},"license":{"name":"Proprietary","url":"https://www.thewedstay.com/terms#api"}},"servers":[{"url":"https://www.thewedstay.com","description":"Production"}],"externalDocs":{"description":"WedStay developer documentation, quickstart, and API keys","url":"https://www.thewedstay.com/developers"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in format: ws_live_..."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-WedStay-Key","description":"The same API key, sent in the X-WedStay-Key header instead of Authorization."}},"schemas":{"VenueListItem":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"property_type":{"type":["string","null"]},"venue_type":{"type":["string","null"]},"capacity_min":{"type":["number","null"]},"capacity_max":{"type":["number","null"]},"bedrooms":{"type":["number","null"]},"beds":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"gathering_spaces":{"type":["number","null"]},"price_range":{"type":["string","null"],"description":"Base price for the whole minimum stay, not per night, before fees, in the venue's listed currency. Example: \"$5,000 to $6,000 for the 2-night minimum (base, before fees)\". For the figure the venue page shows, read pricing.starting_total."},"pricing":{"$ref":"#/components/schemas/VenuePricing"},"hero_image":{"type":["string","null"]},"seo_description":{"type":["string","null"]},"amenities":{"type":"array","items":{"type":"string"}},"url":{"type":"string"}},"required":["slug","name","city","state","country","latitude","longitude","property_type","venue_type","capacity_min","capacity_max","bedrooms","beds","bathrooms","gathering_spaces","price_range","pricing","hero_image","seo_description","amenities","url"]},"VenuePricing":{"type":"object","properties":{"price_unit":{"type":"string","enum":["per_stay"],"description":"The base covers the whole minimum stay"},"currency":{"type":"string","enum":["USD","EUR","AUD"],"description":"The currency the venue page shows. EUR venues are never converted"},"min_nights":{"type":"number"},"weekday_base":{"type":["number","null"],"description":"Weekday base price for the whole minimum stay, not per night"},"weekend_base":{"type":["number","null"],"description":"Weekend base price for the whole minimum stay, not per night"},"extra_night":{"type":["number","null"],"description":"Price of each night beyond the minimum"},"starting_total":{"type":["object","null"],"properties":{"amount":{"type":"number","description":"The venue page's \"Your WedStay starts at\" figure"},"nights":{"type":"number"},"rate":{"type":"string","enum":["weekday","weekend"]},"includes_fees":{"type":"boolean"}},"required":["amount","nights","rate","includes_fees"]},"rate_date":{"type":["string","null"],"description":"Exchange rate date when an AUD conversion was applied"}},"required":["price_unit","currency","min_nights","weekday_base","weekend_base","extra_night","starting_total","rate_date"],"description":"Structured price, in the currency the venue page shows (USD; EUR for venues in euro countries, never converted; AUD for Australian venues). weekday_base and weekend_base are the base price for the whole minimum stay, never per night. starting_total.amount is exactly the venue page's \"Your WedStay starts at\" figure for the minimum stay at the weekday rate."},"Pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"total_count":{"type":"number"}},"required":["has_more","next_cursor","total_count"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"},"doc_url":{"type":"string"}},"required":["type","code","message","request_id"]}},"required":["error"]},"VenueDetail":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"property_type":{"type":["string","null"]},"venue_type":{"type":["string","null"]},"description":{"type":["string","null"]},"seo_description":{"type":["string","null"]},"capacity_min":{"type":["number","null"]},"capacity_max":{"type":["number","null"]},"bedrooms":{"type":["number","null"]},"beds":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"gathering_spaces":{"type":["number","null"]},"accommodates":{"type":["number","null"]},"price_range":{"type":["string","null"],"description":"Base price for the whole minimum stay, not per night, before fees, in the venue's listed currency. Example: \"$5,000 to $6,000 for the 2-night minimum (base, before fees)\". For the figure the venue page shows, read pricing.starting_total."},"pricing":{"$ref":"#/components/schemas/VenuePricing"},"amenities":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"hero_image":{"type":["string","null"]},"photos":{"type":"array","items":{"$ref":"#/components/schemas/VenuePhoto"},"description":"Up to 5 preview photos. Full gallery on venue page."},"total_photos":{"type":"number"},"testimonials":{"type":"array","items":{"$ref":"#/components/schemas/VenueTestimonial"}},"url":{"type":"string"}},"required":["slug","name","city","state","country","latitude","longitude","property_type","venue_type","description","seo_description","capacity_min","capacity_max","bedrooms","beds","bathrooms","gathering_spaces","accommodates","price_range","pricing","amenities","categories","hero_image","photos","total_photos","testimonials","url"]},"VenuePhoto":{"type":"object","properties":{"url":{"type":"string"},"category":{"type":["string","null"]},"is_featured":{"type":"boolean"},"position":{"type":["number","null"]}},"required":["url","category","is_featured","position"]},"VenueTestimonial":{"type":"object","properties":{"guest_name":{"type":["string","null"]},"rating":{"type":["number","null"]},"review":{"type":["string","null"]},"event_date":{"type":["string","null"]}},"required":["guest_name","rating","review","event_date"]},"PricingResult":{"type":"object","properties":{"estimated_total":{"type":"number","description":"All-in regional estimate for the stay, USD"},"price_range":{"type":"string"},"per_night_average":{"type":"number","description":"estimated_total divided by nights: an average for comparison, not a nightly rate any venue charges"},"per_night":{"type":"number","description":"Deprecated (removal after 2027-01-06): same value as per_night_average","deprecated":true},"summary":{"type":"string"},"savings_vs_traditional":{"type":["object","null"],"properties":{"savings_percent":{"type":"number"},"note":{"type":"string"}},"required":["savings_percent","note"]},"parameters":{"type":"object","additionalProperties":{}}},"required":["estimated_total","price_range","per_night_average","per_night","summary","savings_vs_traditional","parameters"]},"CostBenchmarksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CostBenchmarkItem"}},"currency":{"type":"string","enum":["USD"]},"fx":{"type":"object","properties":{"eur_to_usd":{"type":"number","description":"USD per euro applied to euro-priced listings"},"rate_date":{"type":"string"}},"required":["eur_to_usd","rate_date"]},"as_of":{"type":["string","null"]},"source_url":{"type":"string"},"note":{"type":"string","example":"Base price for exclusive use of the entire estate covering the minimum stay (usually 2 nights; 3 to 5 at some properties), not per night, before cleaning, service fee and tax. All figures in USD; euro-priced listings are converted at the rate shown in fx. For a specific venue, use its own pricing: the venue page, the pricing object on the venue endpoints, or calculate_pricing with its slug on MCP."},"request_id":{"type":"string"}},"required":["data","currency","fx","as_of","source_url","note","request_id"]},"CostBenchmarkItem":{"type":"object","properties":{"scope":{"type":"string","description":"national | state | venue_type | country"},"country":{"type":["string","null"]},"state":{"type":["string","null"]},"venue_type":{"type":["string","null"]},"median_base_per_stay":{"type":"number","description":"Median base price for exclusive use covering the whole minimum stay, not per night (USD)"},"typical_low_base_per_stay":{"type":"number","description":"25th percentile base price for the whole minimum stay (USD)"},"typical_high_base_per_stay":{"type":"number","description":"75th percentile base price for the whole minimum stay (USD)"},"converted_from":{"type":["string","null"],"enum":["EUR",null],"description":"EUR when the listings are priced in euro and were converted to USD at fx"},"median_nightly":{"type":"number","description":"Deprecated (removal after 2027-01-06): same value as median_base_per_stay. Never a nightly rate","deprecated":true},"typical_low_nightly":{"type":"number","description":"Deprecated (removal after 2027-01-06): same value as typical_low_base_per_stay","deprecated":true},"typical_high_nightly":{"type":"number","description":"Deprecated (removal after 2027-01-06): same value as typical_high_base_per_stay","deprecated":true},"listings":{"type":"number","description":"Number of live listings behind the figure (min 3)"}},"required":["scope","country","state","venue_type","median_base_per_stay","typical_low_base_per_stay","typical_high_base_per_stay","converted_from","median_nightly","typical_low_nightly","typical_high_nightly","listings"]},"RegionalCostRange":{"type":["object","null"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"state | city"},"coverage":{"type":"string","description":"calculator (the region has its own multipliers) | parent_state (a city borrowing its state multipliers) | insights_only (a published range with national fallback multipliers)"},"matched_on":{"type":"string","description":"slug | city | state | country | alias"},"multipliers_from":{"type":["string","null"],"description":"Set on coverage=parent_state: the slug the multipliers came from"},"range":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"},"display":{"type":"string"},"note":{"type":"string"}},"required":["low","high","display","note"],"description":"The whole wedding budget range, all in. Not a price for a specific venue."},"average_guest_count":{"type":"number","description":"The guest count the published range is built on"},"seasonal_multipliers":{"type":"object","properties":{"peak":{"type":"number"},"shoulder":{"type":"number"},"off_season":{"type":"number"}},"required":["peak","shoulder","off_season"]},"day_of_week_multipliers":{"type":"object","properties":{"friday":{"type":"number"},"saturday":{"type":"number"},"sunday":{"type":"number"}},"required":["friday","saturday","sunday"]},"popular_seasons":{"type":"object","properties":{"peak":{"type":"array","items":{"type":"string"}},"shoulder":{"type":"array","items":{"type":"string"}},"off_season":{"type":"array","items":{"type":"string"}},"best_weather":{"type":"string"}},"required":["peak","shoulder","off_season","best_weather"]},"season":{"type":["object","null"],"properties":{"asked":{"type":"string"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"period":{"type":"string"}},"required":["month","period"]}},"period":{"type":"string","description":"peak | shoulder | offSeason"},"multiplier":{"type":"number"},"unclassified":{"type":"boolean","description":"True when no month of the season appears in any of this region's season lists, so shoulder is a fallback rather than a classification"}},"required":["asked","months","period","multiplier","unclassified"]},"scaled":{"type":["object","null"],"properties":{"low":{"type":"number"},"high":{"type":"number"},"guest_count":{"type":["number","null"]},"guest_multiplier":{"type":"number"},"season_multiplier":{"type":"number"},"clamped":{"type":"boolean"}},"required":["low","high","guest_count","guest_multiplier","season_multiplier","clamped"],"description":"The published range moved by the calculator multipliers. A scaled estimate, never a quote."},"source":{"type":"string","description":"The attribution phrase for these figures"},"data_year":{"type":"number"}},"required":["slug","name","type","coverage","matched_on","multipliers_from","range","average_guest_count","seasonal_multipliers","day_of_week_multipliers","popular_seasons","season","scaled","source","data_year"]},"KnowledgeChunk":{"type":"object","properties":{"title":{"type":"string","description":"The note the section belongs to"},"heading":{"type":"string","description":"The section heading, empty for a note's opening text"},"body":{"type":"string","description":"The authored text, verbatim"},"kind":{"type":"string","description":"knowledge"},"slug":{"type":"string","description":"The note's stable id, e.g. booking/tours-and-deposits"},"score":{"type":"number","description":"Reciprocal rank fusion score across vector and full-text ranks. Higher is closer; not calibrated across queries"}},"required":["title","heading","body","kind","slug","score"]},"VendorListItem":{"type":"object","properties":{"slug":{"type":"string"},"business_name":{"type":"string"},"tagline":{"type":["string","null"]},"service_category":{"type":"string"},"service_subcategories":{"type":["array","null"],"items":{"type":"string"}},"primary_city":{"type":["string","null"]},"primary_state":{"type":["string","null"]},"bio":{"type":["string","null"]},"starting_price":{"type":["number","null"]},"price_unit":{"$ref":"#/components/schemas/PriceUnit"},"years_in_business":{"type":["number","null"]},"weddings_completed":{"type":["number","null"]},"service_areas":{"type":["array","null"],"items":{"type":"string"}},"specialties":{"type":["array","null"],"items":{"type":"string"}},"featured":{"type":["boolean","null"]},"featured_image_url":{"type":["string","null"],"description":"The vendor's primary photo: absolute CDN URL, medium WebP when one exists, else the original."},"logo_url":{"type":["string","null"],"description":"Reserved. Currently always null."},"is_affiliate_only":{"type":"boolean"},"affiliate_link":{"type":["string","null"],"description":"Only populated when is_affiliate_only=true. Inquiry endpoints reject affiliate-only vendors."},"url":{"type":"string"}},"required":["slug","business_name","tagline","service_category","service_subcategories","primary_city","primary_state","bio","starting_price","price_unit","years_in_business","weddings_completed","service_areas","specialties","featured","featured_image_url","logo_url","is_affiliate_only","affiliate_link","url"]},"PriceUnit":{"type":["string","null"],"enum":["per_person","per_event","per_hour","per_item",null],"description":"Display unit for starting_price — null means \"Starting at $X\" with no unit suffix."},"VendorCategory":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"vendor_count":{"type":"number"}},"required":["name","slug","vendor_count"]},"VendorDetail":{"allOf":[{"$ref":"#/components/schemas/VendorListItem"},{"type":"object","properties":{"photos":{"type":"array","items":{"$ref":"#/components/schemas/VendorPhoto"},"description":"Up to 5 portfolio photos, primary first, as absolute CDN URLs. Full portfolio on the vendor page."},"total_photos":{"type":"number"},"website":{"type":["string","null"]},"instagram":{"type":["string","null"]},"facebook":{"type":["string","null"]},"tiktok":{"type":["string","null"]},"pricing_structure":{"type":["string","null"]},"portfolio_description":{"type":["string","null"]},"vendor_policies":{"$ref":"#/components/schemas/VendorPolicies"},"average_rating":{"type":["number","null"]},"review_count":{"type":["number","null"]}},"required":["photos","total_photos","website","instagram","facebook","tiktok","pricing_structure","portfolio_description","vendor_policies","average_rating","review_count"]}]},"VendorPhoto":{"type":"object","properties":{"url":{"type":"string"},"category":{"type":["string","null"]},"alt_text":{"type":["string","null"]}},"required":["url","category","alt_text"]},"VendorPolicies":{"type":["object","null"],"properties":{"booking":{"type":["string","null"]},"payment":{"type":["string","null"]},"cancellation":{"type":["string","null"]},"timeline":{"type":["string","null"]},"insurance":{"type":["string","null"]}}},"InquiryResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"inquiry_id":{"type":"string"},"status":{"type":"string","enum":["submitted"]},"message":{"type":"string"}},"required":["inquiry_id","status","message"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"VenueInquiry":{"type":"object","properties":{"property_slug":{"type":"string","minLength":1},"start_date":{"type":"string","minLength":1},"end_date":{"type":"string","minLength":1},"event_guests":{"type":"number","minimum":1,"maximum":10000},"overnight_guests":{"type":"number","minimum":0,"maximum":10000},"guest_name":{"type":"string","minLength":1,"maxLength":500},"guest_email":{"type":"string","maxLength":500,"format":"email"},"guest_phone":{"type":"string","maxLength":100},"message":{"type":"string","maxLength":5000},"estimated_price":{"type":"integer","minimum":0,"maximum":100000},"sms_consent":{"type":"boolean","description":"Ask the couple: 'OK if WedStay texts you about this request?' Send true only if they said yes."}},"required":["property_slug","start_date","end_date","event_guests","guest_name","guest_email","sms_consent"]},"VendorInquiry":{"type":"object","properties":{"vendor_slug":{"type":"string","minLength":1},"guest_name":{"type":"string","minLength":1,"maxLength":500},"guest_email":{"type":"string","maxLength":500,"format":"email"},"guest_phone":{"type":"string","maxLength":100},"event_date":{"type":"string"},"event_location":{"type":"string","maxLength":500},"event_guests":{"type":"number","minimum":0,"maximum":10000},"budget_range":{"type":"string","maxLength":100},"service_needed":{"type":"string","maxLength":500},"message":{"type":"string","maxLength":5000},"sms_consent":{"type":"boolean","description":"Ask the couple: 'OK if WedStay texts you about this request?' Send true only if they said yes."}},"required":["vendor_slug","guest_name","guest_email","sms_consent"]},"InspirationPhotoListItem":{"type":"object","properties":{"id":{"type":"string"},"image_url":{"type":["string","null"]},"alt":{"type":["string","null"]},"source":{"$ref":"#/components/schemas/InspirationSource"},"styles":{"type":"array","items":{"type":"string"}},"settings":{"type":"array","items":{"type":"string"}},"colors":{"type":"array","items":{"type":"string"}},"moods":{"type":"array","items":{"type":"string"}},"season":{"type":["string","null"]}},"required":["id","image_url","alt","source","styles","settings","colors","moods","season"]},"InspirationSource":{"type":"object","properties":{"type":{"type":"string","enum":["property","vendor"]},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"url":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]}},"required":["type","name","slug","url","city","state"]},"InspirationPagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"has_more":{"type":"boolean"}},"required":["limit","offset","total","has_more"]},"InspirationStyle":{"type":"string","enum":["rustic","modern","bohemian","coastal","luxury","romantic","classic","minimalist"]},"InspirationSetting":{"type":"string","enum":["outdoor","indoor","garden","mountain","beach","lakefront","forest","desert","vineyard","ballroom","tent","poolside"]},"InspirationColor":{"type":"string","enum":["neutral_white","warm","cool","earth_tones","pastel","jewel_tones","moody_dark","vibrant","monochrome"]},"InspirationMood":{"type":"string","enum":["elegant","romantic","serene","intimate","grand","celebratory","joyful","dramatic"]},"InspirationSeason":{"type":"string","enum":["spring","summer","fall","winter"]},"InspirationPhotoDetail":{"allOf":[{"$ref":"#/components/schemas/InspirationPhotoListItem"},{"type":"object","properties":{"description":{"type":["string","null"]},"variants":{"$ref":"#/components/schemas/InspirationPhotoVariants"}},"required":["description","variants"]}]},"InspirationPhotoVariants":{"type":"object","properties":{"small":{"type":["string","null"]},"medium":{"type":["string","null"]},"large":{"type":["string","null"]}},"required":["small","medium","large"]},"BlogPostListItem":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":["string","null"]},"feature_image":{"type":["string","null"]},"published_at":{"type":"string"},"reading_time":{"type":["number","null"]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/BlogTag"}},"primary_author":{"$ref":"#/components/schemas/BlogAuthor"},"url":{"type":"string"}},"required":["slug","title","excerpt","feature_image","published_at","reading_time","tags","primary_author","url"]},"BlogTag":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"]},"BlogAuthor":{"type":["object","null"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"}},"required":["name","slug","url"]},"BlogPagination":{"type":"object","properties":{"limit":{"type":"number"},"page":{"type":"number"},"has_more":{"type":"boolean"}},"required":["limit","page","has_more"]},"BlogPostDetail":{"allOf":[{"$ref":"#/components/schemas/BlogPostListItem"},{"type":"object","properties":{"word_count":{"type":"number"},"content_plaintext":{"type":["string","null"]}},"required":["word_count","content_plaintext"]}]},"BlogTagWithCount":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"post_count":{"type":"number"}},"required":["slug","name","post_count"]}},"parameters":{}},"paths":{"/api/v1/venues":{"get":{"operationId":"listVenues","summary":"Search wedding venues","description":"Find wedding venues by location, capacity, budget, venue type, and amenities. Returns paginated results with cursor-based pagination.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"city","in":"query"},{"schema":{"type":"string","description":"Venue type (case-insensitive substring match on the venue's property type): estate, villa, ranch, mansion, cabin, castle, chalet, lodge, cottage, barn, barndominium, hacienda, farmhouse, chateau"},"required":false,"description":"Venue type (case-insensitive substring match on the venue's property type): estate, villa, ranch, mansion, cabin, castle, chalet, lodge, cottage, barn, barndominium, hacienda, farmhouse, chateau","name":"venue_type","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"capacity_min","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"capacity_max","in":"query"},{"schema":{"type":["number","null"],"description":"Minimum pricing.starting_total.amount (the venue page's \"starts at\" for the minimum stay), in each venue's listed currency. Venues with no listed price are left out"},"required":false,"description":"Minimum pricing.starting_total.amount (the venue page's \"starts at\" for the minimum stay), in each venue's listed currency. Venues with no listed price are left out","name":"price_min","in":"query"},{"schema":{"type":["number","null"],"description":"Maximum pricing.starting_total.amount, in each venue's listed currency: euro venues compare in euros, Australian venues in Australian dollars. Venues with no listed price are left out"},"required":false,"description":"Maximum pricing.starting_total.amount, in each venue's listed currency: euro venues compare in euros, Australian venues in Australian dollars. Venues with no listed price are left out","name":"price_max","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"bedrooms_min","in":"query"},{"schema":{"type":"string"},"required":false,"name":"amenities","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A list of matching venues","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VenueListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"required":["data","pagination","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/venues/{slug}":{"get":{"operationId":"getVenue","summary":"Get venue details","description":"Get full details for a specific wedding venue including photos, testimonials, amenities, and capacity information.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","description":"The full slug from search results, URL-encoded (its slashes become %2F).","example":"california/palm-springs/palm-springs-wedding-estate-with-retro-pool-vibes-hollywood-history-sleeps-12"},"required":true,"description":"The full slug from search results, URL-encoded (its slashes become %2F).","name":"slug","in":"path"}],"responses":{"200":{"description":"Full venue details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VenueDetail"},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Venue not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/venues/pricing":{"get":{"operationId":"calculateVenuePricing","summary":"Calculate wedding pricing","description":"Calculate estimated wedding costs by region, guest count, venue type, and season. Returns estimated total, price range, and savings comparison.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","default":"california","description":"A region id, name or common short form (case insensitive). An unknown region is a 400 that lists the ids: california, new-york, texas, florida, michigan, colorado, north-carolina, tennessee, georgia, utah, new-jersey, massachusetts, pennsylvania, illinois, virginia, washington, arizona, oregon, mexico, italy, italy-tuscany, italy-lake-como, italy-amalfi-coast, italy-sicily, italy-puglia, italy-umbria, italy-rome, italy-florence, italy-venice, australia, other","example":"italy-tuscany"},"required":false,"description":"A region id, name or common short form (case insensitive). An unknown region is a 400 that lists the ids: california, new-york, texas, florida, michigan, colorado, north-carolina, tennessee, georgia, utah, new-jersey, massachusetts, pennsylvania, illinois, virginia, washington, arizona, oregon, mexico, italy, italy-tuscany, italy-lake-como, italy-amalfi-coast, italy-sicily, italy-puglia, italy-umbria, italy-rome, italy-florence, italy-venice, australia, other","name":"region","in":"query"},{"schema":{"type":"string","enum":["weekday","weekend"],"default":"weekend"},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":500,"default":100},"required":false,"name":"event_guests","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":350,"default":20},"required":false,"name":"overnight_guests","in":"query"},{"schema":{"type":"number","minimum":2,"maximum":7,"default":2},"required":false,"name":"nights","in":"query"},{"schema":{"type":"string","enum":["barn","estate","resort","winery","garden","historic","ranch","villa"],"default":"estate"},"required":false,"name":"venue_type","in":"query"},{"schema":{"type":"string","enum":["peak","shoulder","off"],"default":"peak"},"required":false,"name":"season","in":"query"}],"responses":{"200":{"description":"Pricing breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PricingResult"},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/cost-benchmarks":{"get":{"operationId":"getCostBenchmarks","summary":"Get wedding venue cost benchmarks","description":"Median and typical-range base prices to rent the entire estate for its minimum stay, by US state, venue type, or country, computed from live listings (minimum 3 per figure). Figures are per stay, not per night, in USD (euro-priced listings converted at the fx rate reported), before fees. With no filter, returns the full national, per-state, per-venue-type, and per-country breakdown. Backs the Wedding Venue Cost Index.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","description":"US state name to filter to a single state row","example":"Texas"},"required":false,"description":"US state name to filter to a single state row","name":"state","in":"query"},{"schema":{"type":"string","description":"Venue type row: estate, villa, ranch, or mansion"},"required":false,"description":"Venue type row: estate, villa, ranch, or mansion","name":"venue_type","in":"query"},{"schema":{"type":"string","description":"Country for a destination row","example":"Mexico"},"required":false,"description":"Country for a destination row","name":"country","in":"query"}],"responses":{"200":{"description":"Cost benchmark rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostBenchmarksResponse"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/regional-cost-ranges":{"get":{"operationId":"getRegionalCostRanges","summary":"Get regional wedding cost ranges","description":"The whole wedding budget range for a US state, city, or destination country, all in, from WedStay 2026 regional data, with that region's average guest count, its peak/shoulder/off-season multipliers, its Friday/Saturday/Sunday multipliers, and the months in each season. Pass season and guests to get the range scaled for them. Different from /api/v1/cost-benchmarks, which returns per-stay base prices for the whole estate computed from live listings. A region with no data returns covered=false and the list of covered regions, never a substituted neighbour.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","description":"Exact region slug from covered_regions","example":"california"},"required":false,"description":"Exact region slug from covered_regions","name":"slug","in":"query"},{"schema":{"type":"string","description":"State name or USPS code, a destination country, or a colloquial region","example":"California"},"required":false,"description":"State name or USPS code, a destination country, or a colloquial region","name":"state","in":"query"},{"schema":{"type":"string","description":"City name or slug","example":"Los Angeles"},"required":false,"description":"City name or slug","name":"city","in":"query"},{"schema":{"type":"string","description":"spring, summer, fall, autumn, winter, a month name, or 01-12","example":"summer"},"required":false,"description":"spring, summer, fall, autumn, winter, a month name, or 01-12","name":"season","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2000,"description":"Scales the range from the region average guest count","example":50},"required":false,"description":"Scales the range from the region average guest count","name":"guests","in":"query"}],"responses":{"200":{"description":"The region's cost ranges, or covered=false when we hold no data for it","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RegionalCostRange"},"covered":{"type":"boolean"},"reason":{"type":"string"},"asked":{"type":"string"},"covered_regions":{"type":"array","items":{"type":"string"}},"as_of":{"type":"number"},"note":{"type":"string"},"source_url":{"type":"string"},"request_id":{"type":"string"}},"required":["data","covered","as_of","note","source_url","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"No region given, or an unparseable season","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/knowledge/search":{"get":{"operationId":"searchKnowledge","summary":"Search WedStay planning notes and policies","description":"WedStay's own authored planning notes and policies (how booking works, tours and deposits, cancellations, property rules, insurance and the vendor COI, the Collective, WedStay One), searched by meaning and by words and fused by reciprocal rank fusion. Returns the closest sections with their note titles, verbatim. Couple-facing knowledge only: no internal notes, no property-specific notes, no partner catalog. Quote what it returns; never paraphrase a policy into a promise, and never treat it as a price for a specific property or as availability.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":300,"description":"The question, in the couple's own words","example":"is the tour deposit refundable"},"required":true,"description":"The question, in the couple's own words","name":"q","in":"query"},{"schema":{"type":"string","description":"Comma-separated boost tags; a tag never filters, it only ranks a matching section higher","example":"deposit,tour"},"required":false,"description":"Comma-separated boost tags; a tag never filters, it only ranks a matching section higher","name":"tags","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"description":"Sections to return, 1 to 10. Default 5","example":5},"required":false,"description":"Sections to return, 1 to 10. Default 5","name":"limit","in":"query"}],"responses":{"200":{"description":"The closest sections, in rank order. degraded=text_only when the semantic half of the search was unavailable and only word matching ran","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}},"query":{"type":"string"},"as_of":{"type":"string"},"note":{"type":"string"},"degraded":{"type":"string"},"request_id":{"type":"string"}},"required":["data","query","as_of","note","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"q missing or outside 3 to 300 characters, or a bad limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"503":{"description":"The knowledge store is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/vendors":{"get":{"operationId":"listVendors","summary":"Search wedding vendors","description":"Find wedding vendors by category (11 types), location, price range, and specialties.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"location","in":"query"},{"schema":{"type":"string"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"city","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"price_min","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"price_max","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"featured","in":"query"},{"schema":{"type":"string","enum":["newest","price_low_to_high","price_high_to_low","experience","weddings_completed"],"default":"newest"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A list of matching vendors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VendorListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"category_stats":{"type":"object","additionalProperties":{"type":"number"}},"request_id":{"type":"string"}},"required":["data","pagination","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/vendors/categories":{"get":{"operationId":"listVendorCategories","summary":"List vendor categories","description":"Get all 11 vendor service categories with the count of active vendors in each.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VendorCategory"}},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/vendors/{slug}":{"get":{"operationId":"getVendor","summary":"Get vendor details","description":"Get full profile for a specific wedding vendor including bio, portfolio, pricing, and service areas.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","example":"sidpix-studios"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Full vendor profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VendorDetail"},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/inquiries/venue":{"post":{"operationId":"createVenueInquiry","summary":"Submit venue booking request","description":"Creates a real lead; requires the user's explicit go-ahead. Submits a booking request for a wedding venue into WedStay's pipeline. A WedStay concierge replies within 24 hours. sms_consent is required. Rate limited to 5/day on free tier.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Optional. A unique string identifying this submission. Retrying with the same key returns the original response instead of creating a second lead. Reusing a key with a different body returns 409. Keys are remembered for 24 hours. Without this header the request body is fingerprinted, so identical retries are still deduplicated.","example":"muse-booking-01HZY5K9"},"required":false,"description":"Optional. A unique string identifying this submission. Retrying with the same key returns the original response instead of creating a second lead. Reusing a key with a different body returns 409. Keys are remembered for 24 hours. Without this header the request body is fingerprinted, so identical retries are still deduplicated.","name":"X-Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueInquiry"}}}},"responses":{"201":{"description":"Inquiry submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryResponse"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"sms_consent missing or not a boolean (invalid_request_error, code sms_consent_required, param sms_consent), invalid JSON, or a field that fails validation (validation_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Venue not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"409":{"description":"conflict: idempotency_conflict (this X-Idempotency-Key was used with a different request body) or idempotency_in_progress (a request with this key is still processing; retry in a few seconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Inquiry rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/inquiries/vendor":{"post":{"operationId":"createVendorInquiry","summary":"Submit vendor contact request","description":"Creates a real lead; requires the user's explicit go-ahead. Sends a contact request to a wedding vendor. Screened by WedStay, then sent to the vendor, who replies within 3 business days. sms_consent is required. Rate limited to 5/day on free tier.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Optional. A unique string identifying this submission. Retrying with the same key returns the original response instead of creating a second lead. Reusing a key with a different body returns 409. Keys are remembered for 24 hours. Without this header the request body is fingerprinted, so identical retries are still deduplicated.","example":"muse-booking-01HZY5K9"},"required":false,"description":"Optional. A unique string identifying this submission. Retrying with the same key returns the original response instead of creating a second lead. Reusing a key with a different body returns 409. Keys are remembered for 24 hours. Without this header the request body is fingerprinted, so identical retries are still deduplicated.","name":"X-Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorInquiry"}}}},"responses":{"201":{"description":"Inquiry submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryResponse"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"sms_consent missing or not a boolean (invalid_request_error, code sms_consent_required, param sms_consent), invalid JSON, or a field that fails validation (validation_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"409":{"description":"conflict: idempotency_conflict (this X-Idempotency-Key was used with a different request body) or idempotency_in_progress (a request with this key is still processing; retry in a few seconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Inquiry rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/inspiration":{"get":{"operationId":"listInspiration","summary":"Search wedding inspiration photos","description":"Search 2,800+ curated wedding inspiration photos by style, setting, color palette, mood, or season. Every photo links back to the bookable source venue or vendor page.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/InspirationStyle"},"required":false,"name":"style","in":"query"},{"schema":{"$ref":"#/components/schemas/InspirationSetting"},"required":false,"name":"setting","in":"query"},{"schema":{"$ref":"#/components/schemas/InspirationColor"},"required":false,"name":"color","in":"query"},{"schema":{"$ref":"#/components/schemas/InspirationMood"},"required":false,"name":"mood","in":"query"},{"schema":{"$ref":"#/components/schemas/InspirationSeason"},"required":false,"name":"season","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"A page of inspiration photos matching the filters","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InspirationPhotoListItem"}},"pagination":{"$ref":"#/components/schemas/InspirationPagination"},"request_id":{"type":"string"}},"required":["data","pagination","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/v1/inspiration/{id}":{"get":{"operationId":"getInspiration","summary":"Get inspiration photo details","description":"Get full details for a specific wedding inspiration photo — including CDN variant URLs (small/medium/large), tag metadata, and the source venue or vendor page for booking.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","example":"551cf0a7-487d-4dc9-bc6f-86b708c91e13"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Inspiration photo detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InspirationPhotoDetail"},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Photo not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/blog/posts":{"get":{"operationId":"listBlogPosts","summary":"Search blog posts","description":"Search WedStay wedding blog posts by tag, keyword, or featured status. Posts cover wedding planning, trends, venue features, and DIY tips.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"tag","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"featured","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":25,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","minimum":1,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"A page of blog posts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlogPostListItem"}},"pagination":{"$ref":"#/components/schemas/BlogPagination"},"request_id":{"type":"string"}},"required":["data","pagination","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/blog/posts/{slug}":{"get":{"operationId":"getBlogPost","summary":"Get blog post details","description":"Get full details and plaintext content for a specific blog post by slug.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"schema":{"type":"string","example":"top-wedding-trends-2026"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Full blog post detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BlogPostDetail"},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}},"404":{"description":"Blog post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/blog/tags":{"get":{"operationId":"listBlogTags","summary":"List blog tags","description":"Get all blog tags with their active post counts, sorted by most posts first. Use these slugs to filter /v1/blog/posts.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"List of blog tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlogTagWithCount"}},"request_id":{"type":"string"}},"required":["data","request_id"]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute: the API key tier's per-minute limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets, as a Unix timestamp in seconds.","schema":{"type":"integer"}}}}}}}},"webhooks":{}}