{"openapi":"3.0.3","info":{"title":"True North Tires Customer Catalog API","version":"1.0.0","description":"Public read-only product search. CAD prices exclude taxes, shipping, tire levies and promotions. Destination-eligible inventory is from the last completed sync, not live or reserved. No checkout or shipping guarantees. Text searches scan at most 200 candidates; no pagination."},"servers":[{"url":"https://finder.truenorthtires.ca"}],"externalDocs":{"description":"Usage guide, limitations and customer prompt","url":"https://finder.truenorthtires.ca/catalog-api.md"},"security":[],"paths":{"/api/muse/catalog-search":{"get":{"operationId":"searchCustomerCatalog","summary":"Find customer tires or wheels for a selected province","description":"Provide q OR all of make/model/year/trim. Any vehicle field requires all four. Vehicle fields take precedence over q; category wheel is rejected. Vehicle mode uses cached Finder sizes and each option's minimum load/speed requirements, returns selectable verified matches only, and returns their union, not an axle package. Load the exact selection in Finder first; uncached fitments return 404. Wheel specifications are not vehicle-fitment certification. 30 requests per IP per rolling minute per process, including invalid requests.","parameters":[{"name":"province","in":"query","required":true,"description":"Selected province; trimmed and uppercased. Territories unsupported.","schema":{"type":"string","pattern":"^\\s*([Nn][LlSsBb]|[Pp][Ee]|[Qq][Cc]|[Oo][Nn]|[Mm][Bb]|[Ss][Kk]|[Aa][Bb]|[Bb][Cc])\\s*$"},"example":"NL"},{"name":"q","in":"query","description":"Required except in vehicle mode. Trimmed length 2–100; no %, underscore or backslash. Start with tire size or wheel diameter x width and optional bolt pattern; trailing words are one substring filter. Otherwise substring keyword search.","schema":{"type":"string","minLength":2,"maxLength":100,"pattern":"^[^%_\\\\]+$"},"examples":{"tire":{"value":"205/55R16"},"wheel":{"value":"17x7.5 5x114.3"},"keyword":{"value":"Michelin"}}},{"name":"category","in":"query","schema":{"type":"string","enum":["all","tire","wheel"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"make","in":"query","description":"Exact Finder make identifier. Requires model, year and trim.","schema":{"type":"string","minLength":1,"maxLength":80},"example":"Honda"},{"name":"model","in":"query","description":"Exact Finder model identifier.","schema":{"type":"string","minLength":1,"maxLength":100},"example":"Civic"},{"name":"year","in":"query","schema":{"type":"string","pattern":"^\\d{4}$"},"example":"2020"},{"name":"trim","in":"query","description":"Exact Finder trim identifier, not a guessed label.","schema":{"type":"string","minLength":1,"maxLength":100},"example":"EX"}],"responses":{"200":{"description":"Customer-safe result; an empty products array is a successful search.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, max-age=30; inventory freshness is independent."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResult"}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchError"}}}},"404":{"description":"No verified Finder fitment is cached, or cached fitment has no valid tire sizes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchError"}}}},"429":{"description":"Search limit reached. Retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchError"}}},"headers":{"Retry-After":{"schema":{"type":"integer","enum":[60]},"description":"Wait 60 seconds."}}},"500":{"description":"Catalog search failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchError"}}}}}}}},"components":{"schemas":{"CustomerProduct":{"type":"object","additionalProperties":false,"required":["handle","title","brand","category","productUrl","priceEach","priceForFourBeforeTaxesShippingAndPromotions","currency","availableQuantityForProvince","singleSourceSetOfFourAvailable","preorder"],"properties":{"handle":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string","enum":["tire","wheel"]},"productUrl":{"type":"string","format":"uri","pattern":"^https://truenorthtires\\.ca/products/"},"priceEach":{"type":"number","minimum":0,"description":"CAD per item; excludes taxes, shipping, tire levies and promotions."},"priceForFourBeforeTaxesShippingAndPromotions":{"type":"number","minimum":0,"description":"Arithmetic price for four; also excludes tire levies. Not a checkout quote."},"currency":{"type":"string","enum":["CAD"]},"availableQuantityForProvince":{"type":"integer","minimum":0},"singleSourceSetOfFourAvailable":{"type":"boolean"},"preorder":{"type":"boolean","description":"Approved preorder, potentially zero on-hand stock."},"finderCompatibility":{"type":"string","enum":["verified","unknown","blocked"],"description":"Optional Finder classification; vehicle searches return verified selectable matches only. Size-only classification does not certify vehicle fitment."},"selectable":{"type":"boolean","description":"Optional alongside finderCompatibility. False means review-only, not a verified selectable tire."}}},"CatalogSearchResult":{"type":"object","additionalProperties":false,"required":["query","province","category","searchMode","inventoryAsOf","inventoryNote","products","count","resultsMayBeIncomplete"],"properties":{"query":{"type":"string"},"province":{"type":"string","enum":["NL","NS","NB","PE","QC","ON","MB","SK","AB","BC"]},"category":{"type":"string","enum":["all","tire","wheel"]},"searchMode":{"type":"string","enum":["exact-tire-size","wheel-specification","text","vehicle-fitment"]},"inventoryAsOf":{"type":"string","nullable":true,"description":"Last completed product sync timestamp string, or null. Not live inventory."},"inventoryNote":{"type":"string"},"products":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/CustomerProduct"}},"count":{"type":"integer","minimum":0,"maximum":20,"description":"Returned count, not total matches."},"resultsMayBeIncomplete":{"type":"boolean","description":"Text scan hit 200 candidates. False does not exclude truncation by limit."}}},"SearchError":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}}