{"info":{"title":"Fire Truck Mall Inventory API","version":"1.0.0","description":"Public, read-only API for searching used fire truck and fire apparatus listings. No authentication required. Quote-only listings return price: null with price_text \"Contact for Quote\". See /api/docs for human documentation and /llms.txt for an LLM-oriented summary."},"servers":[{"url":"https://sandbox.firetruckmall.com"}],"openapi":"3.1.1","paths":{"/api/v1/listings/search":{"get":{"operationId":"searchFireTruckListings","summary":"Search and filter used fire truck listings.","description":"Search available fire apparatus inventory by region, apparatus type, make/brand, price, year, mileage, pump GPM, tank gallons, aerial length, warranty, status, and free-text keyword query. No authentication required. Returns listing summaries with canonical URLs — never requires parsing HTML.","tags":["Public Inventory"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","description":"Free-text keyword query matched against title, brand, model, description, stock number, city, and feature keywords (max 200 chars). Example: q=pierce aerial ladder"},"allowReserved":true},{"name":"status","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"default":["available"],"description":"Listing availability filter. Accepts repeated params or comma-separated values. One of: available, hold, sold. Defaults to available. Example: status=available,hold"},"allowReserved":true},{"name":"apparatus_type","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Apparatus categories. Accepts repeated params or comma-separated values. One of: engine, aerial, tower, rescue, ambulance, command, brush, tanker, arff, hazmat, demo, equipment, custom. Example: apparatus_type=aerial"},"allowReserved":true},{"name":"brand","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Manufacturer/make names, case-insensitive. Accepts repeated params or comma-separated values. Use GET /filter-options for the live brand vocabulary. Example: brand=pierce,e-one"},"allowReserved":true},{"name":"region","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"US sales regions. Accepts repeated params or comma-separated values. One of: northeast, midwest, south, southwest, west, international. Example: region=midwest"},"allowReserved":true},{"name":"state","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Two-letter US state/territory codes (e.g. TX, CA, NY) or INT for international. Accepts repeated params or comma-separated values, case-insensitive. Example: state=TX,OK"},"allowReserved":true},{"name":"chassis_type","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Chassis style. Accepts repeated params or comma-separated values. One of: custom, commercial, commercial_2_door, commercial_4_door. Example: chassis_type=custom"},"allowReserved":true},{"name":"min_year","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum model year, inclusive (1900-2100). Example: min_year=2005"},"allowReserved":true},{"name":"max_year","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum model year, inclusive (1900-2100). Example: max_year=2020"},"allowReserved":true},{"name":"min_price","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum price in whole US dollars, inclusive. Quote-only listings (price: null) are excluded from price-filtered results unless include_quote_only=true. Example: min_price=50000"},"allowReserved":true},{"name":"max_price","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum price in whole US dollars, inclusive. Quote-only listings (price: null) are excluded from price-filtered results unless include_quote_only=true. Example: max_price=250000"},"allowReserved":true},{"name":"include_quote_only","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"When true, listings without a published price (\"Contact for Quote\") are included even when min_price/max_price are set. Example: include_quote_only=true"},"allowReserved":true},{"name":"min_mileage","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum odometer mileage in miles, inclusive. Example: min_mileage=10000"},"allowReserved":true},{"name":"max_mileage","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum odometer mileage in miles, inclusive. Example: max_mileage=80000"},"allowReserved":true},{"name":"min_pump_gpm","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum fire pump capacity in gallons per minute (GPM), inclusive. Example: min_pump_gpm=1500"},"allowReserved":true},{"name":"max_pump_gpm","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum fire pump capacity in gallons per minute (GPM), inclusive. Example: max_pump_gpm=2000"},"allowReserved":true},{"name":"min_tank_gallons","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum water tank size in US gallons, inclusive. Example: min_tank_gallons=750"},"allowReserved":true},{"name":"max_tank_gallons","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum water tank size in US gallons, inclusive. Example: max_tank_gallons=3000"},"allowReserved":true},{"name":"min_aerial_ft","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Minimum aerial ladder/platform length in feet, inclusive. Example: min_aerial_ft=75"},"allowReserved":true},{"name":"max_aerial_ft","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Maximum aerial ladder/platform length in feet, inclusive. Example: max_aerial_ft=110"},"allowReserved":true},{"name":"warranty_only","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"When true, only listings sold with a warranty are returned. Example: warranty_only=true"},"allowReserved":true},{"name":"sort","in":"query","schema":{"enum":["relevance","newest","price_asc","price_desc","year_desc","mileage_asc"],"default":"relevance","description":"Result ordering. One of: relevance, newest, price_asc, price_desc, year_desc, mileage_asc. Defaults to relevance. Example: sort=price_asc"},"allowReserved":true},{"name":"page","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"1-based page number (1-10000). Defaults to 1. Example: page=2"},"allowReserved":true},{"name":"page_size","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Results per page (1-50). Defaults to 20. Example: page_size=50"},"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sort":{"enum":["relevance","newest","price_asc","price_desc","year_desc","mileage_asc"]},"inventory_updated_at":{"type":"string","format":"date-time"},"applied_filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable listing/stock number exposed to users."},"uuid":{"type":"string","format":"uuid","description":"Opaque internal identifier."},"title":{"type":"string"},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"brand":{"type":"string","description":"Manufacturer/make, e.g. Pierce, E-One."},"model":{"anyOf":[{"type":"string"},{"type":"null"}]},"apparatus_type":{"anyOf":[{"enum":["engine","aerial","tower","rescue","ambulance","command","brush","tanker","arff","hazmat","demo","equipment","custom"]},{"type":"null"}]},"chassis_type":{"anyOf":[{"enum":["custom","commercial","commercial_2_door","commercial_4_door"]},{"type":"null"}]},"status":{"enum":["available","hold","sold"]},"price":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"USD price; null when price is not published."},"price_text":{"type":"string","description":"Display label, e.g. \"Contact for Quote\"."},"mileage":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"pump_gpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"tank_gallons":{"anyOf":[{"type":"number"},{"type":"null"}]},"aerial_length_ft":{"anyOf":[{"type":"number"},{"type":"null"}]},"region":{"anyOf":[{"enum":["northeast","midwest","south","southwest","west","international"]},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"warranty":{"type":"boolean"},"canonical_url":{"type":"string","format":"uri"},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"listing_updated_at":{"type":"string","format":"date-time"}},"required":["id","uuid","title","year","brand","model","apparatus_type","chassis_type","status","price","price_text","mileage","pump_gpm","tank_gallons","aerial_length_ft","region","state","features","warranty","canonical_url","image_url","listing_updated_at"]}}},"required":["total","page","page_size","sort","inventory_updated_at","applied_filters","results"]}}}},"400":{"description":"Invalid query parameter, enum value, or impossible range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded; see Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/listings/{id}":{"get":{"operationId":"getFireTruckListing","summary":"Get full public details for one fire truck listing.","description":"Fetch one listing by its stable listing/stock number (e.g. \"20956\") or UUID. Returns 404 for unknown or non-public listings.","tags":["Public Inventory"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Stable listing/stock number exposed to users."},"uuid":{"type":"string","format":"uuid","description":"Opaque internal identifier."},"title":{"type":"string"},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"brand":{"type":"string","description":"Manufacturer/make, e.g. Pierce, E-One."},"model":{"anyOf":[{"type":"string"},{"type":"null"}]},"apparatus_type":{"anyOf":[{"enum":["engine","aerial","tower","rescue","ambulance","command","brush","tanker","arff","hazmat","demo","equipment","custom"]},{"type":"null"}]},"chassis_type":{"anyOf":[{"enum":["custom","commercial","commercial_2_door","commercial_4_door"]},{"type":"null"}]},"status":{"enum":["available","hold","sold"]},"price":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"USD price; null when price is not published."},"price_text":{"type":"string","description":"Display label, e.g. \"Contact for Quote\"."},"mileage":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"pump_gpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"tank_gallons":{"anyOf":[{"type":"number"},{"type":"null"}]},"aerial_length_ft":{"anyOf":[{"type":"number"},{"type":"null"}]},"region":{"anyOf":[{"enum":["northeast","midwest","south","southwest","west","international"]},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"warranty":{"type":"boolean"},"canonical_url":{"type":"string","format":"uri"},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"listing_updated_at":{"type":"string","format":"date-time"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"condition":{"anyOf":[{"type":"string"},{"type":"null"}]},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"alt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","alt"]}}},"required":["id","uuid","title","year","brand","model","apparatus_type","chassis_type","status","price","price_text","mileage","pump_gpm","tank_gallons","aerial_length_ft","region","state","features","warranty","canonical_url","image_url","listing_updated_at","description","city","condition","images"]}}}},"400":{"description":"Invalid query parameter, enum value, or impossible range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Listing ID not found or not publicly visible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded; see Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/filter-options":{"get":{"operationId":"getFireTruckFilterOptions","summary":"List supported filters, enum values, ranges, and counts.","description":"Returns the filter vocabulary AI tools should prefer: apparatus types, brands, regions, chassis types (with live counts of available listings), plus year/price ranges and mileage/pump/tank buckets.","tags":["Public Inventory"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"inventory_updated_at":{"type":"string","format":"date-time"},"apparatus_type":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["value","label"]}},"brands":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["value","label"]}},"regions":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["value","label"]}},"chassis_type":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["value","label"]}},"ranges":{"type":"object","properties":{"year":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["min","max"]},"price":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["min","max"]},"mileage":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"string"}}},"required":["buckets"]},"pump_gpm":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"string"}}},"required":["buckets"]},"tank_gallons":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"string"}}},"required":["buckets"]}},"required":["year","price","mileage","pump_gpm","tank_gallons"]}},"required":["inventory_updated_at","apparatus_type","brands","regions","chassis_type","ranges"]}}}},"400":{"description":"Invalid query parameter, enum value, or impossible range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded; see Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/regions":{"get":{"operationId":"getFireTruckRegions","summary":"List supported sales regions and their state mappings.","tags":["Public Inventory"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"value":{"enum":["northeast","midwest","south","southwest","west","international"]},"label":{"type":"string"},"states":{"type":"array","items":{"type":"string"}}},"required":["value","label","states"]}}},"required":["regions"]}}}},"400":{"description":"Invalid query parameter, enum value, or impossible range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded; see Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"security":[],"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}}}