{"openapi":"3.1.0","info":{"title":"DealFinder by Cottontail API","version":"0.4.0","description":"Lowest-price lookup and purchase links for AI assistants and agents. Results are ranked by total price only; some links carry a disclosed affiliate code. The same two operations are available over MCP at /mcp."},"servers":[{"url":"https://gocottontail.com"}],"security":[{"bearer":[]},{}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Partner API key. Omit for anonymous use (attributed to the house account)."}},"schemas":{"Offer":{"type":"object","properties":{"rank":{"type":"integer"},"merchant":{"type":"string"},"title":{"type":"string"},"price":{"type":"number"},"shipping":{"type":["number","null"]},"total":{"type":"number"},"total_is_estimate":{"type":"boolean"},"condition":{"type":"string"},"currency":{"type":"string"},"url":{"type":"string","format":"uri"},"affiliate":{"type":["string","null"]},"note":{"type":"string"}}},"FindResponse":{"type":"object","properties":{"query":{"type":"string"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"disclosure":{"type":"string"},"price_source":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"product_page":{"type":"string","format":"uri"}}},"ResolveResponse":{"type":"object","properties":{"original":{"type":"string"},"url":{"type":"string","format":"uri"},"affiliate":{"type":["string","null"]},"existing_tag_preserved":{"type":"boolean"},"note":{"type":"string"},"disclosure":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/v1/find":{"post":{"operationId":"findBestPrice","summary":"Find the lowest total price for a named product","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product"],"properties":{"product":{"type":"string","minLength":3,"maxLength":200},"max_results":{"type":"integer","minimum":1,"maximum":10,"default":5},"include_used":{"type":"boolean","default":false,"description":"Also include used, open-box and refurbished listings."}}}}}},"responses":{"200":{"description":"Offers ranked by total price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid API key"},"429":{"description":"Rate limited"}}}},"/api/v1/resolve":{"post":{"operationId":"resolveLink","summary":"Return a product URL as an affiliate link when one is available; never alters the destination or an existing tag","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2000}}}}}},"responses":{"200":{"description":"Resolved link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveResponse"}}}},"400":{"description":"Bad request"},"401":{"description":"Invalid API key"}}}},"/api/v1/watch":{"post":{"operationId":"watchPrice","summary":"Set a one-time SMS alert for when a product's lowest total price reaches a target (only when alerts are enabled on the server)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","target_price","phone"],"properties":{"product":{"type":"string"},"target_price":{"type":"number"},"phone":{"type":"string","description":"Mobile number the user explicitly provided, E.164 preferred"}}}}}},"responses":{"200":{"description":"Watch set","content":{"application/json":{"schema":{"type":"object","properties":{"watch_token":{"type":"string"},"product":{"type":"string"},"target_price":{"type":"number"},"expires_at":{"type":"string"},"cancel_url":{"type":"string"}}}}}},"400":{"description":"Invalid input or alerts not enabled"}}}},"/healthz":{"get":{"operationId":"health","summary":"Service health and provider status","security":[],"responses":{"200":{"description":"OK"}}}}}}