{"openapi":"3.1.0","info":{"title":"Paw Pantry Connector API","description":"Stateless pet-supply search and refill estimates for Muse. This contract cannot access Paw Pantry's private pet-profile workspace. Inventory matches include a first-party Paw Pantry guidance page and a tagged retailer search action. Show every returned affiliate disclosure beside its retailer action and open retailer URLs only after a user chooses them.","version":"0.14.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"check_service_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"summary":"Ready","description":"Connector readiness without revealing credentials or database details.","operationId":"check_connector_readiness","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/products":{"get":{"summary":"List Products","description":"Search products and return display-ready retailer buttons and disclosures.\n\nClients may surface each `retailer_options` entry directly. They must show its\ndisclosure with the button and open the URL only after the user chooses it.","operationId":"search_curated_products","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"species","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Species"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Category"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"},"title":"Response Search Curated Products"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/catalog-stats":{"get":{"summary":"Catalog Stats","description":"Public, non-sensitive counts describing the current connector inventory.","operationId":"get_catalog_statistics","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogStats"}}}}}}},"/inventory":{"get":{"summary":"Inventory","description":"Search broad product-type coverage; records are not live retailer stock.","operationId":"search_product_type_inventory","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"species","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Species"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Category"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryListing"},"title":"Response Search Product Type Inventory"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/shopping-options":{"get":{"summary":"Shopping Options","description":"Return ranked catalog matches plus a broader, user-initiated Amazon search.\n\nUse this operation for open-ended shopping requests. Curated products have\nindividually verified variants. The broader Amazon action opens changing search\nresults, so the client must not describe it as a specific recommendation.","operationId":"find_shopping_options","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Q"}},{"name":"species","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Species"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Category"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingOptionsResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/products/{product_id}/link":{"get":{"summary":"Product Link","description":"Return one display-ready, user-initiated affiliate retailer action.","operationId":"get_retailer_link","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"integer","title":"Product Id"}},{"name":"retailer","in":"query","required":false,"schema":{"enum":["amazon","chewy"],"type":"string","default":"amazon","title":"Retailer"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductLinkResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/refill-estimate":{"post":{"summary":"Refill Estimate","description":"Calculate a refill estimate without storing a pet profile or supply record.","operationId":"estimate_refill_date","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefillEstimateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefillEstimateResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"CatalogProduct":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"brand":{"type":"string","title":"Brand"},"species":{"type":"string","title":"Species"},"category":{"type":"string","title":"Category"},"package_size":{"type":"string","title":"Package Size"},"notes":{"type":"string","title":"Notes"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url"},"catalog_status":{"type":"string","enum":["active","retired"],"title":"Catalog Status"},"replacement_product_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Replacement Product Id"},"amazon_link_available":{"type":"boolean","title":"Amazon Link Available"},"verified_amazon_product_link":{"type":"boolean","title":"Verified Amazon Product Link"},"affiliate_search_available":{"type":"boolean","title":"Affiliate Search Available"},"chewy_link_available":{"type":"boolean","title":"Chewy Link Available"},"retailer_options":{"items":{"$ref":"#/components/schemas/RetailerOption"},"type":"array","title":"Retailer Options"}},"type":"object","required":["id","name","brand","species","category","package_size","notes","website_url","catalog_status","replacement_product_id","amazon_link_available","verified_amazon_product_link","affiliate_search_available","chewy_link_available","retailer_options"],"title":"CatalogProduct"},"CatalogStats":{"properties":{"active_curated_products":{"type":"integer","title":"Active Curated Products"},"retired_products":{"type":"integer","title":"Retired Products"},"shopping_intents":{"type":"integer","title":"Shopping Intents"},"verified_amazon_products":{"type":"integer","title":"Verified Amazon Products"},"affiliate_enabled_active_products":{"type":"integer","title":"Affiliate Enabled Active Products"},"affiliate_enabled_intents":{"type":"integer","title":"Affiliate Enabled Intents"},"verified_chewy_products":{"type":"integer","title":"Verified Chewy Products"},"species_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Species Counts"},"category_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Category Counts"},"shopping_species_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Shopping Species Counts"},"shopping_category_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Shopping Category Counts"},"broader_amazon_search_enabled":{"type":"boolean","title":"Broader Amazon Search Enabled"},"first_party_recommendation_pages":{"type":"integer","title":"First Party Recommendation Pages"},"semantic_search_enabled":{"type":"boolean","title":"Semantic Search Enabled"},"semantic_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Semantic Model"}},"type":"object","required":["active_curated_products","retired_products","shopping_intents","verified_amazon_products","affiliate_enabled_active_products","affiliate_enabled_intents","verified_chewy_products","species_counts","category_counts","shopping_species_counts","shopping_category_counts","broader_amazon_search_enabled","first_party_recommendation_pages","semantic_search_enabled","semantic_model"],"title":"CatalogStats"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InventoryListing":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"species":{"type":"string","title":"Species"},"category":{"type":"string","title":"Category"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"guidance":{"type":"string","title":"Guidance"},"base_intent_id":{"type":"string","title":"Base Intent Id"},"variant_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Label"},"website_url":{"type":"string","title":"Website Url"},"retailer_options":{"items":{"$ref":"#/components/schemas/RetailerOption"},"type":"array","title":"Retailer Options"}},"type":"object","required":["id","title","species","category","keywords","guidance","base_intent_id","website_url","retailer_options"],"title":"InventoryListing"},"ProductLinkResult":{"properties":{"product":{"$ref":"#/components/schemas/CatalogProduct"},"retailer":{"type":"string","enum":["amazon","chewy"],"title":"Retailer"},"destination":{"type":"string","title":"Destination"},"button_label":{"type":"string","title":"Button Label"},"url":{"type":"string","title":"Url"},"disclosure":{"type":"string","title":"Disclosure"},"kind":{"type":"string","enum":["product","search"],"title":"Kind","default":"product"},"affiliate":{"type":"boolean","title":"Affiliate","default":true},"opens_after_user_click":{"type":"boolean","title":"Opens After User Click","default":true},"rel":{"type":"string","title":"Rel","default":"sponsored nofollow noopener"},"source_page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Page Url"}},"type":"object","required":["product","retailer","destination","button_label","url","disclosure"],"title":"ProductLinkResult"},"RefillEstimateRequest":{"properties":{"purchase_date":{"type":"string","format":"date","title":"Purchase Date"},"package_amount":{"type":"number","maximum":1000000.0,"exclusiveMinimum":0.0,"title":"Package Amount"},"daily_use":{"type":"number","maximum":1000000.0,"exclusiveMinimum":0.0,"title":"Daily Use"},"unit":{"type":"string","maxLength":24,"minLength":1,"title":"Unit"},"reorder_lead_days":{"type":"integer","maximum":365.0,"minimum":0.0,"title":"Reorder Lead Days","default":5}},"additionalProperties":false,"type":"object","required":["purchase_date","package_amount","daily_use","unit"],"title":"RefillEstimateRequest"},"RefillEstimateResult":{"properties":{"days_total":{"type":"number","title":"Days Total"},"days_left":{"type":"number","title":"Days Left"},"runs_out":{"type":"string","format":"date","title":"Runs Out"},"reorder_by":{"type":"string","format":"date","title":"Reorder By"},"overdue":{"type":"boolean","title":"Overdue"},"unit":{"type":"string","title":"Unit"},"guidance":{"type":"string","title":"Guidance"}},"type":"object","required":["days_total","days_left","runs_out","reorder_by","overdue","unit","guidance"],"title":"RefillEstimateResult"},"RetailerOption":{"properties":{"retailer":{"type":"string","enum":["amazon","chewy"],"title":"Retailer"},"destination":{"type":"string","title":"Destination"},"button_label":{"type":"string","title":"Button Label"},"url":{"type":"string","title":"Url"},"disclosure":{"type":"string","title":"Disclosure"},"kind":{"type":"string","enum":["product","search"],"title":"Kind","default":"product"},"affiliate":{"type":"boolean","title":"Affiliate","default":true},"opens_after_user_click":{"type":"boolean","title":"Opens After User Click","default":true},"rel":{"type":"string","title":"Rel","default":"sponsored nofollow noopener"},"source_page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Page Url"}},"type":"object","required":["retailer","destination","button_label","url","disclosure"],"title":"RetailerOption","description":"A user-initiated external retailer action that a connector may render."},"ShoppingOptionsResult":{"properties":{"query":{"type":"string","title":"Query"},"interpreted_query":{"type":"string","title":"Interpreted Query"},"curated_products":{"items":{"$ref":"#/components/schemas/CatalogProduct"},"type":"array","title":"Curated Products"},"matched_inventory":{"items":{"$ref":"#/components/schemas/InventoryListing"},"type":"array","title":"Matched Inventory"},"broader_amazon_search":{"$ref":"#/components/schemas/RetailerOption"},"matching_method":{"type":"string","enum":["keyword","hybrid-semantic"],"title":"Matching Method"},"semantic_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Semantic Model"},"guidance":{"type":"string","title":"Guidance"}},"type":"object","required":["query","interpreted_query","curated_products","matched_inventory","broader_amazon_search","matching_method","semantic_model","guidance"],"title":"ShoppingOptionsResult"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://paw-pantry.onrender.com"}]}