{"openapi":"3.1.0","info":{"title":"Fyndl API","version":"7eb09bbca4146f061cd7b4f82be714fa752372e8","description":"Fyndl refurbished-MacBook search and offers API. /v1 is the canonical, brand-neutral surface; the unversioned /remtio paths remain a deprecated legacy alias with identical schemas, status codes, and auth. Agents can also use the MCP endpoint at POST /mcp (streamable HTTP, stateless)."},"paths":{"/health":{"get":{"summary":"Service health","responses":{"200":{"description":"Service health","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["status","timestamp"],"additionalProperties":false}}}}}}},"/ready":{"get":{"summary":"Readiness status","responses":{"200":{"description":"Readiness status","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"checks":{"type":"object","properties":{"process":{"type":"string","const":"ok"},"consultationPersistence":{"type":"string","enum":["ok","memory","unavailable"]}},"required":["process","consultationPersistence"],"additionalProperties":false},"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["status","checks","timestamp"],"additionalProperties":false}}}}}}},"/version":{"get":{"summary":"Runtime version metadata","responses":{"200":{"description":"Runtime version metadata","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"node":{"type":"string"}},"required":["name","version","node"],"additionalProperties":false}}}}}}},"/v1/search":{"get":{"summary":"Search refurbished MacBook offers (ranked, with reasons)","parameters":[{"name":"q","in":"query","required":true,"description":"Natural-language query, e.g. \"MacBook Air M1 unter 700 Euro guter Zustand\"","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":1000}}],"responses":{"200":{"description":"Ranked MacBook offers with scores, reasons, and advisor summary, or an explicit unsupported_category state with no ranked offers.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"status":{"default":"ok","type":"string","const":"ok"},"query":{"type":"object","properties":{"rawQuery":{"type":"string","minLength":1},"brand":{"type":"string","minLength":1,"maxLength":64},"category":{"default":"macbook","type":"string","enum":["macbook","iphone","ipad","smartwatch","monitor","desktop"]},"categorySource":{"default":"rules","type":"string","enum":["rules","model"]},"model":{"type":"string","minLength":1},"maxPrice":{"type":"number","exclusiveMinimum":0},"minPrice":{"type":"number","exclusiveMinimum":0},"color":{"type":"string","minLength":1},"minYear":{"type":"integer","minimum":2006,"maximum":9007199254740991},"currency":{"default":"EUR","type":"string","const":"EUR"},"minimumCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"requiredSpecs":{"default":{},"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"}},"additionalProperties":false},"minScreenInches":{"type":"number","exclusiveMinimum":0},"maxScreenInches":{"type":"number","exclusiveMinimum":0},"screenInchesAnyOf":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number","exclusiveMinimum":0}},"excludedTitleTerms":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"niceToHaveSpecs":{"default":[],"type":"array","items":{"type":"string","minLength":1}}},"required":["rawQuery","category","categorySource","currency","requiredSpecs","niceToHaveSpecs"],"additionalProperties":false},"results":{"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"score":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"positives":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"tradeoffs":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"default":"rules","type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","positives","tradeoffs","generatedBy"],"additionalProperties":false}},"required":["offer","rank","score","reason"],"additionalProperties":false}},"unsupportedCategory":{"not":{}},"id":{"type":"string","minLength":1},"advisor":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"bestPickOfferId":{"type":"string","minLength":1},"nextQuestions":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","nextQuestions","generatedBy"],"additionalProperties":false},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live","mixed"]},"disclaimer":{"type":"string","minLength":1},"persisted":{"default":false,"type":"boolean"}},"required":["status","query","results","generatedAt","dataMode","persisted"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"unsupported_category"},"query":{"type":"object","properties":{"rawQuery":{"type":"string","minLength":1}},"required":["rawQuery"],"additionalProperties":false},"results":{"minItems":0,"maxItems":0,"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"score":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"positives":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"tradeoffs":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"default":"rules","type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","positives","tradeoffs","generatedBy"],"additionalProperties":false}},"required":["offer","rank","score","reason"],"additionalProperties":false}},"unsupportedCategory":{"type":"object","properties":{"detectedCategory":{"type":"string","enum":["iphone","ipad","smartphone","kopfhoerer","smartwatch","fitnesstracker","konsole","fernseher","monitor","kamera","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne","unknown"]},"reason":{"type":"string","enum":["recognized_unsupported_category","ambiguous_category_intent","insufficient_category_confidence"]},"supportedCategories":{"minItems":1,"type":"array","items":{"type":"string","enum":["macbook","iphone","ipad","smartwatch","monitor","desktop"]}}},"required":["detectedCategory","reason","supportedCategories"],"additionalProperties":false},"id":{"type":"string","minLength":1},"advisor":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"bestPickOfferId":{"type":"string","minLength":1},"nextQuestions":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","nextQuestions","generatedBy"],"additionalProperties":false},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live","mixed"]},"disclaimer":{"type":"string","minLength":1},"persisted":{"default":false,"type":"boolean"}},"required":["status","query","results","unsupportedCategory","generatedAt","dataMode","persisted"],"additionalProperties":false}]}}}},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}},"post":{"summary":"Search refurbished MacBook offers (ranked, with reasons)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":1000},"queryId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["q"],"additionalProperties":false}}}},"responses":{"200":{"description":"Ranked MacBook offers with scores, reasons, and advisor summary, or an explicit unsupported_category state with no ranked offers.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"status":{"default":"ok","type":"string","const":"ok"},"query":{"type":"object","properties":{"rawQuery":{"type":"string","minLength":1},"brand":{"type":"string","minLength":1,"maxLength":64},"category":{"default":"macbook","type":"string","enum":["macbook","iphone","ipad","smartwatch","monitor","desktop"]},"categorySource":{"default":"rules","type":"string","enum":["rules","model"]},"model":{"type":"string","minLength":1},"maxPrice":{"type":"number","exclusiveMinimum":0},"minPrice":{"type":"number","exclusiveMinimum":0},"color":{"type":"string","minLength":1},"minYear":{"type":"integer","minimum":2006,"maximum":9007199254740991},"currency":{"default":"EUR","type":"string","const":"EUR"},"minimumCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"requiredSpecs":{"default":{},"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"}},"additionalProperties":false},"minScreenInches":{"type":"number","exclusiveMinimum":0},"maxScreenInches":{"type":"number","exclusiveMinimum":0},"screenInchesAnyOf":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number","exclusiveMinimum":0}},"excludedTitleTerms":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"niceToHaveSpecs":{"default":[],"type":"array","items":{"type":"string","minLength":1}}},"required":["rawQuery","category","categorySource","currency","requiredSpecs","niceToHaveSpecs"],"additionalProperties":false},"results":{"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"score":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"positives":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"tradeoffs":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"default":"rules","type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","positives","tradeoffs","generatedBy"],"additionalProperties":false}},"required":["offer","rank","score","reason"],"additionalProperties":false}},"unsupportedCategory":{"not":{}},"id":{"type":"string","minLength":1},"advisor":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"bestPickOfferId":{"type":"string","minLength":1},"nextQuestions":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","nextQuestions","generatedBy"],"additionalProperties":false},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live","mixed"]},"disclaimer":{"type":"string","minLength":1},"persisted":{"default":false,"type":"boolean"}},"required":["status","query","results","generatedAt","dataMode","persisted"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"unsupported_category"},"query":{"type":"object","properties":{"rawQuery":{"type":"string","minLength":1}},"required":["rawQuery"],"additionalProperties":false},"results":{"minItems":0,"maxItems":0,"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"score":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"positives":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"tradeoffs":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"default":"rules","type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","positives","tradeoffs","generatedBy"],"additionalProperties":false}},"required":["offer","rank","score","reason"],"additionalProperties":false}},"unsupportedCategory":{"type":"object","properties":{"detectedCategory":{"type":"string","enum":["iphone","ipad","smartphone","kopfhoerer","smartwatch","fitnesstracker","konsole","fernseher","monitor","kamera","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne","unknown"]},"reason":{"type":"string","enum":["recognized_unsupported_category","ambiguous_category_intent","insufficient_category_confidence"]},"supportedCategories":{"minItems":1,"type":"array","items":{"type":"string","enum":["macbook","iphone","ipad","smartwatch","monitor","desktop"]}}},"required":["detectedCategory","reason","supportedCategories"],"additionalProperties":false},"id":{"type":"string","minLength":1},"advisor":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"bestPickOfferId":{"type":"string","minLength":1},"nextQuestions":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","nextQuestions","generatedBy"],"additionalProperties":false},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live","mixed"]},"disclaimer":{"type":"string","minLength":1},"persisted":{"default":false,"type":"boolean"}},"required":["status","query","results","unsupportedCategory","generatedAt","dataMode","persisted"],"additionalProperties":false}]}}}},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}}},"/v1/search/explain":{"post":{"summary":"Model-written explanations and advisor text for offers already on screen (AI-assisted)","description":"The search itself returns rules-based reasons. Call this only for the offers a buyer actually opens; it is one model round trip.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":1000},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"offerIds":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"required":["q","offerIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Explained offers plus advisor summary; rules text when the model is off or fails.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"score":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"positives":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"tradeoffs":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"default":"rules","type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","positives","tradeoffs","generatedBy"],"additionalProperties":false}},"required":["offer","rank","score","reason"],"additionalProperties":false}},"advisor":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"bestPickOfferId":{"type":"string","minLength":1},"nextQuestions":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","minLength":1}},"generatedBy":{"type":"string","enum":["rules","bedrock","openai"]}},"required":["summary","nextQuestions","generatedBy"],"additionalProperties":false}},"required":["results","advisor"],"additionalProperties":false}}}},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}}},"/v1/offers":{"get":{"summary":"List current offers (live if ingested, sample otherwise)","parameters":[{"name":"category","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"description":"Catalog category key. A key names a device class, not a brand: `macbook` is Laptops (mostly Dell, Lenovo and HP), `iphone` is Smartphones (Samsung, Xiaomi, Google). Each returned offer's `category` is the class stored on that row, never an echo of this parameter. Category requests are paginated by default."},{"name":"page","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"integer","exclusiveMinimum":0,"maximum":100000},"description":"One-based result page."},{"name":"pageSize","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"integer","exclusiveMinimum":0,"maximum":1000},"description":"Offers per page, capped at 1000."}],"responses":{"200":{"description":"Current offer inventory","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false}},"dataMode":{"default":"sample","type":"string","enum":["sample","manual","live","mixed"]},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"pagination":{"type":"object","properties":{"page":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"pageSize":{"type":"integer","exclusiveMinimum":0,"maximum":1000},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalPages":{"type":"integer","minimum":0,"maximum":9007199254740991},"hasNextPage":{"type":"boolean"}},"required":["page","pageSize","total","totalPages","hasNextPage"],"additionalProperties":false}},"required":["offers","dataMode","generatedAt"],"additionalProperties":false}}}}}}},"/v1/offers-index":{"get":{"summary":"Offer ids and timestamps only — the sitemap's view of the catalog","responses":{"200":{"description":"Every offer, reduced to id and lastUpdated","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","lastUpdated"],"additionalProperties":false}},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["offers","generatedAt"],"additionalProperties":false}}}}}}},"/v1/product-chat":{"post":{"summary":"Stateless product Q&A grounded on catalog offers (AI-assisted, fallback text when AI is off)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":1000},"offerIds":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"required":["question","offerIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Grounded answer or deterministic fallback","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"answer":{"type":"string","minLength":1,"maxLength":2000},"generatedBy":{"type":"string","enum":["openai","fallback","deterministic"]}},"required":["answer","generatedBy"],"additionalProperties":false}}}},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}}},"/v1/offers/{id}":{"get":{"summary":"Get one offer with price history and market context","parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100},"description":"Offer id from a search or list response"}],"responses":{"200":{"description":"Offer detail with observed price history","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"category":{"type":"string","enum":["macbook","iphone","airpods","ipad","smartwatch","fitnesstracker","fernseher","monitor","kamera","konsole","desktop","pc-zubehoer","drucker","netzwerk","lautsprecher","kuechengeraete","staubsauger","kaffeemaschine","emobilitaet","werkzeug","smarthome","drohne"]},"brand":{"type":"string","minLength":1,"maxLength":64},"model":{"type":"string","minLength":1},"specs":{"type":"object","properties":{"chip":{"type":"string","minLength":1},"gpu":{"type":"string","minLength":1,"maxLength":64},"memoryGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"storageGb":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"screenInches":{"type":"number","exclusiveMinimum":0},"year":{"type":"integer","minimum":2006,"maximum":9007199254740991},"color":{"type":"string","minLength":1},"ports":{"minItems":1,"type":"array","items":{"type":"string","enum":["hdmi","usb_a","usb_c","thunderbolt","magsafe","sd_card","headphone_jack"]}},"ean":{"type":"string","pattern":"^\\d{8,14}$"},"batteryHealthPercent":{"type":"integer","minimum":0,"maximum":100},"simLock":{"type":"string","enum":["unlocked","locked","unknown"]},"generation":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"connector":{"type":"string","enum":["lightning","usb_c","unknown"]}},"additionalProperties":false},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"referencePrice":{"type":"number","exclusiveMinimum":0},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trustNotes":{"default":[],"type":"array","items":{"type":"string","minLength":1}},"dataMode":{"type":"string","enum":["sample","manual","live"]},"newPrice":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"avgPrice90Days":{"type":"number","exclusiveMinimum":0},"sourcePlatform":{"type":"string","const":"idealo"},"sourceUrl":{"type":"string","format":"uri"}},"required":["price","currency","sourcePlatform","sourceUrl"],"additionalProperties":false}},"required":["id","productName","category","brand","model","specs","conditionLabel","normalizedCondition","price","currency","sourcePlatform","sourceUrl","availability","lastUpdated","trustNotes","dataMode"],"additionalProperties":false},"priceHistory":{"default":[],"type":"array","items":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"observedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["price","observedAt"],"additionalProperties":false}},"priceContext":{"type":"object","properties":{"modelMedian":{"type":"number","exclusiveMinimum":0},"deltaToMedianPct":{"type":"number"},"cohortSize":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["modelMedian","deltaToMedianPct","cohortSize"],"additionalProperties":false},"alternatives":{"default":[],"maxItems":6,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"productName":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"price":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","const":"EUR"},"conditionLabel":{"type":"string","minLength":1},"normalizedCondition":{"type":"string","enum":["poor","fair","good","very_good","excellent","like_new","unknown"]},"sourcePlatform":{"type":"string","enum":["apple_store","acer_refurbished","microsoft_refurbished","asus_refurbished","back_market","refurbed","rebuy","idealo","ebay_refurbished","amazon_renewed","asgoodasnew","esm_computer","alternate","maconline","janado","handingo","mobilshop3000","it_versand","hardware_hexe","notebookgalerie","computeroutlet","horch_und_guck","one_de","manual_sample","other"]},"sellerName":{"type":"string","minLength":1,"maxLength":120},"sellerFeedbackPct":{"type":"number","minimum":0,"maximum":100},"warrantyMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"availability":{"type":"string","enum":["available","limited","unavailable","unknown"]},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"sourceUrl":{"type":"string","format":"uri"},"purchaseUrl":{"description":"Canonical, tracked purchase link (https://fyndl.online/out/<id>). Use this when linking a buyer to the offer; sourceUrl is the raw merchant link.","type":"string","format":"uri"},"productUrl":{"description":"Fyndl product page for this offer (https://fyndl.online/angebot/<slug>--<id>). Cite this as the product page.","type":"string","format":"uri"}},"required":["id","productName","model","price","currency","conditionLabel","normalizedCondition","sourcePlatform","availability","lastUpdated","sourceUrl"],"additionalProperties":false}},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["offer","priceHistory","alternatives","generatedAt"],"additionalProperties":false}}}},"404":{"description":"Unknown offer id"}}}},"/v1/out/{offerId}":{"get":{"summary":"Canonical purchase link: redirect to the merchant with affiliate attribution","description":"The canonical purchase URL of an offer is https://fyndl.online/out/{offerId}; it relays here. The offer id is the only input, the destination comes from the catalog, never from the request (no open redirect). Affiliate parameters are appended server-side, so agents without a browser keep attribution. One click row is stored without IP or raw referrer (user agent capped at 256 chars); rows are deleted after REMTIO_ANALYTICS_RETENTION_DAYS. Every response is cache-control: no-store and x-robots-tag: noindex.","parameters":[{"name":"offerId","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100},"description":"Offer id from a search, list or detail response"},{"name":"src","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^[a-z_]{1,32}$"},"description":"Surface the click came from (detail, search, agent, ...)"},{"name":"utm_source","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100},"description":"Traffic source; an AI assistant host (chatgpt.com, perplexity.ai) is classified as ai"},{"name":"utm_medium","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100}},{"name":"utm_campaign","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100}},{"name":"sid","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Anonymous session id (UUID); anything else is ignored"}],"responses":{"302":{"description":"Redirect to the merchant or affiliate network (Location header)"},"400":{"description":"Malformed offer id: { error: { code: \"outbound_rejected\" } }"},"404":{"description":"Unknown offer id: { error: { code: \"offer_not_found\" } }"},"410":{"description":"Offer sold or stale; fallback.path is a relative Fyndl path (offer page or category)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","const":"offer_expired"},"message":{"type":"string","minLength":1}},"required":["code","message"],"additionalProperties":false},"fallback":{"type":"object","properties":{"path":{"type":"string","pattern":"^\\/.*"}},"required":["path"],"additionalProperties":false}},"required":["error","fallback"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded"}}}},"/v1/events/click":{"post":{"summary":"Record one offer click as a search-quality ranking signal","description":"The click is stored: its result position is the denominator of the position-corrected ranking. Rows are deleted once they are older than REMTIO_SEARCH_SIGNAL_RETENTION_DAYS (180 by default). The consent-gated product analytics is a separate endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"searchId":{"type":"string","minLength":1,"maxLength":100},"offerId":{"type":"string","minLength":1,"maxLength":100},"sourceUrl":{"type":"string","format":"uri"},"surface":{"type":"string","const":"browse"},"context":{"type":"string","enum":["search","browse"]},"resultPosition":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"placement":{"type":"string","enum":["primary","expanded"]},"offerPosition":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["offerId","sourceUrl"],"additionalProperties":false}}}},"responses":{"200":{"description":"Persistence result { id, persisted }"},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."},"429":{"description":"Rate limit exceeded"}}}},"/v1/events/search-impressions":{"post":{"summary":"Record deduplicated visible offer impressions for one search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"impressions":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"searchId":{"type":"string","minLength":1,"maxLength":100},"offerId":{"type":"string","minLength":1,"maxLength":100},"resultPosition":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"placement":{"type":"string","enum":["primary","expanded"]},"offerPosition":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["searchId","offerId","resultPosition","placement"],"additionalProperties":false}}},"required":["impressions"],"additionalProperties":false}}}},"responses":{"200":{"description":"Persistence result { inserted, persisted }"},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."},"429":{"description":"Rate limit exceeded"}}}},"/v1/events/analytics":{"post":{"summary":"Record a consented, pseudonymous web growth event","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"eventType":{"type":"string","enum":["page_view","search_started","search_completed","outbound_offer_click","watchlist_added","feedback_submitted","lead_submitted","ai_crawler_hit","ai_referral_hit","ai_agent_hit"]},"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"attribution":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9._/-]+$"},"medium":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9._/-]+$"},"campaign":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9._/-]+$"}},"required":["source"],"additionalProperties":false},"landingPath":{"type":"string","maxLength":200,"pattern":"^\\/.*"},"partner":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[A-Za-z0-9._/-]+$"},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["eventType","sessionId","attribution","landingPath"],"additionalProperties":false}}}},"responses":{"200":{"description":"Persistence result { id, persisted }"},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}}},"/v1/feedback":{"post":{"summary":"Record user feedback on a search or offer","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","enum":["offer","app"]},"searchId":{"type":"string","minLength":1,"maxLength":100},"offerId":{"type":"string","minLength":1,"maxLength":100},"usefulness":{"type":"string","enum":["useful","not_useful","unsure"]},"trust":{"type":"string","enum":["trusted","not_trusted","unsure"]},"rating":{"type":"integer","minimum":1,"maximum":5},"message":{"type":"string","minLength":1,"maxLength":2000},"contactEmail":{"type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"survey":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","first_time"]},"categories":{"maxItems":24,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"recommend":{"type":"integer","minimum":1,"maximum":5}},"additionalProperties":false},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["usefulness"],"additionalProperties":false}}}},"responses":{"200":{"description":"Persistence result { id, persisted }"},"400":{"description":"Invalid request. Zod validation errors return { error: { code: \"bad_request\", message, details } }."}}}}}}