{"openapi":"3.1.0","info":{"title":"RV Chooser Marketplace API","version":"2.0.0","description":"Unified search over used RVs listings with model-level specs, market comparison, de-duplication, anonymous personalization and buyer lead capture."},"paths":{"/api/inventory":{"get":{"summary":"Search listings (de-duplicated by default) with filters, sorting, pagination and facet counts","parameters":[{"name":"q","in":"query","required":false,"description":"Full-text search (make, model, category, location, description)","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Normalized category; repeat or comma-separate","schema":{"type":"string"}},{"name":"make","in":"query","required":false,"description":"Make; multi","schema":{"type":"string"}},{"name":"model","in":"query","required":false,"description":"Normalized model key; multi","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"US state code; multi","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"City; multi","schema":{"type":"string"}},{"name":"minPrice","in":"query","required":false,"description":"USD","schema":{"type":"number"}},{"name":"maxPrice","in":"query","required":false,"description":"USD","schema":{"type":"number"}},{"name":"year","in":"query","required":false,"description":"","schema":{"type":"integer"}},{"name":"minYear","in":"query","required":false,"description":"","schema":{"type":"integer"}},{"name":"maxYear","in":"query","required":false,"description":"","schema":{"type":"integer"}},{"name":"minHours","in":"query","required":false,"description":"","schema":{"type":"integer"}},{"name":"maxHours","in":"query","required":false,"description":"","schema":{"type":"integer"}},{"name":"hasPrice","in":"query","required":false,"description":"1 = only priced listings","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"","schema":{"type":"string","enum":["relevance","price_asc","price_desc","year_desc","year_asc","hours_asc","hours_desc","newest"]}},{"name":"page","in":"query","required":false,"description":"1-based","schema":{"type":"integer"}},{"name":"pageSize","in":"query","required":false,"description":"1-100 (default 24)","schema":{"type":"integer"}},{"name":"track","in":"query","required":false,"description":"0 = don't record as a personalization signal","schema":{"type":"string"}}],"responses":{"200":{"description":"{ total, page, pageSize, totalPages, items[], facets{category,make,model,state,location}, ranges }"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiInventory","description":"Search listings (de-duplicated by default) with filters, sorting, pagination and facet counts"}},"/api/inventory/{id}":{"get":{"summary":"One listing with model specs and price history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listing"},"404":{"description":"Not found"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiInventoryBy_id","description":"One listing with model specs and price history"}},"/api/compare":{"get":{"summary":"Side-by-side comparison: specs, market median for comparable listings, deal score, similar listings","parameters":[{"name":"ids","in":"query","required":false,"description":"Comma-separated listing ids (max 4)","schema":{"type":"string"}}],"responses":{"200":{"description":"{ spec_keys[], items[{...listing, model_specs, market{n,median,p25,p75,med_hours,basis}, deal{score,label,price_vs_market_pct}, similar[]}] }"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiCompare","description":"Side-by-side comparison: specs, market median for comparable listings, deal score, similar listings"}},"/api/recommendations":{"get":{"summary":"Recommendations for the current visitor (uid cookie or X-User-Id header)","parameters":[{"name":"limit","in":"query","required":false,"description":"max 24","schema":{"type":"integer"}},{"name":"similarTo","in":"query","required":false,"description":"seed listing id","schema":{"type":"string"}}],"responses":{"200":{"description":"{ strategy, profile, items[] with score & reasons }"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiRecommendations","description":"Recommendations for the current visitor (uid cookie or X-User-Id header)"}},"/api/leads":{"post":{"summary":"Submit a buyer request (availability, quote, financing, inspection) for a listing or in general","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"intent":{"enum":["availability","quote","financing","inspection","general"]},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"zip":{"type":"string"},"timeline":{"enum":["asap","30d","90d","researching"]},"message":{"type":"string"}},"required":["name","email"]}}}},"responses":{"201":{"description":"{ ok, leadId }"},"400":{"description":"validation error"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"postApiLeads","description":"Submit a buyer request (availability, quote, financing, inspection) for a listing or in general"}},"/api/market":{"get":{"summary":"Public market aggregates (index, or ?category=<slug> / ?model=<make-model slug>) with as_of date and attribution","parameters":[{"name":"category","in":"query","required":false,"description":"Category slug","schema":{"type":"string"}},{"name":"model","in":"query","required":false,"description":"Model slug","schema":{"type":"string"}}],"responses":{"200":{"description":"{ type, as_of, stats{n,median,p25,p75,min,max,med_hours}, price_by_year[], hours_distribution[], ... }"},"404":{"description":"{ error{code,message,resolution} }"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiMarket","description":"Public market aggregates (index, or ?category=<slug> / ?model=<make-model slug>) with as_of date and attribution"}},"/api/favorites":{"get":{"summary":"List favorites","responses":{"200":{"description":"{ items[] }"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"getApiFavorites","description":"List favorites"},"post":{"summary":"Add/remove favorite","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string"},"favorite":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"ok"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"postApiFavorites","description":"Add/remove favorite"}},"/api/events":{"post":{"summary":"Record an interaction signal","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"enum":["view","filter","search","click_rec","favorite","compare"]},"itemId":{"type":"string"},"payload":{"type":"object"}},"required":[]}}}},"responses":{"200":{"description":"ok"},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"operationId":"postApiEvents","description":"Record an interaction signal"}}},"servers":[{"url":"https://rvchooser.com"}]}