{"openapi":"3.1.0","x-product-id":"price-compare","info":{"title":"Price Compare API","version":"1.0.0","summary":"Search products, compare delivered prices, inspect price history, and manage price watches.","description":"The canonical contract for the Price Compare SDKs. Comparisons combine normalized product identity, current delivered offers, availability, seller terms, and historical price signals.","contact":{"name":"Nordic Devhouse SDK Maintainers","email":"sdk@nordicdevhouse.com","url":"https://github.com/X42NORDIC/price-compare-sdk"},"license":{"name":"MIT","identifier":"MIT","url":"https://opensource.org/license/mit"}},"servers":[{"url":"https://api.pricecompare.nordicdevhouse.com/v1","description":"Production"},{"url":"https://sandbox.pricecompare.nordicdevhouse.com/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Catalog","description":"Search the normalized product catalog."},{"name":"Comparisons","description":"Read decision-ready product and offer comparisons."},{"name":"Price history","description":"Inspect historical price intelligence."},{"name":"Watchlists","description":"Manage client-scoped price watches."}],"paths":{"/search":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"tags":["Catalog"],"operationId":"searchProducts","summary":"Search normalized products","description":"Searches product names, aliases, models, variants, and EAN identifiers and ranks matches by relevance and current minimum price.","x-sdk-test":{"role":"primary-read"},"parameters":[{"$ref":"#/components/parameters/SearchQuery"}],"responses":{"200":{"description":"Ranked product matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"400":["validation_error"],"401":["authentication_error"],"429":["rate_limited"],"500":["server_error"]}}},"/compare":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"tags":["Comparisons"],"operationId":"compareProducts","summary":"Compare two to four products","description":"Returns a single decision-ready comparison for products in the same comparable category.","parameters":[{"$ref":"#/components/parameters/ProductIds"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Goal"}],"responses":{"200":{"description":"Product comparison","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComparisonResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"400":["validation_error"],"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}}},"/products/{canonical_product_id}":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/ProductId"}],"get":{"tags":["Comparisons"],"operationId":"getProductComparison","summary":"Get one product and its current offers","responses":{"200":{"description":"Product identity, offers, and recommendation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductComparison"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}}},"/products/{canonical_product_id}/history":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/ProductId"}],"get":{"tags":["Price history"],"operationId":"getProductPriceHistory","summary":"Get product or store price history","description":"Returns aggregate price intelligence by default or chronological store price points when store is supplied.","parameters":[{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Store"}],"responses":{"200":{"description":"Price intelligence or store history","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PriceIntelligence"},{"$ref":"#/components/schemas/StorePriceHistory"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"400":["validation_error"],"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}}},"/watchlists":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/ClientId"}],"get":{"tags":["Watchlists"],"operationId":"listPriceWatches","summary":"List price watches","responses":{"200":{"description":"Client-scoped watches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"401":["authentication_error"],"429":["rate_limited"],"500":["server_error"]}},"post":{"tags":["Watchlists"],"operationId":"createPriceWatch","summary":"Create or replace a product price watch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceWatchInput"},"example":{"canonical_product_id":"sony_wh1000xm5_black","target_price":280,"channel":"email","destination":"buyer@example.com"}}}},"responses":{"201":{"description":"Price watch created","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceWatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"400":["validation_error"],"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}}},"/watchlists/{watch_id}":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/ClientId"},{"$ref":"#/components/parameters/WatchId"}],"patch":{"tags":["Watchlists"],"operationId":"updatePriceWatch","summary":"Update a price watch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceWatchPatch"},"example":{"target_price":265,"status":"active"}}}},"responses":{"200":{"description":"Updated price watch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceWatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"400":["validation_error"],"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}},"delete":{"tags":["Watchlists"],"operationId":"deletePriceWatch","summary":"Delete a price watch","responses":{"204":{"description":"Price watch deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-error-codes":{"401":["authentication_error"],"404":["not_found"],"429":["rate_limited"],"500":["server_error"]}}}},"components":{"parameters":{"ApiVersion":{"name":"X-API-Version","in":"header","required":false,"schema":{"type":"string","default":"1"}},"SearchQuery":{"name":"q","in":"query","required":true,"description":"Product name, model, alias, or EAN.","example":"sony xm5","schema":{"type":"string","minLength":1,"maxLength":120}},"ProductIds":{"name":"ids","in":"query","required":true,"description":"Comma-separated list of two to four canonical product identifiers.","example":"sony_wh1000xm5_black,sony_wh1000xm6_black","schema":{"type":"string","minLength":3}},"ProductId":{"name":"canonical_product_id","in":"path","required":true,"example":"sony_wh1000xm5_black","schema":{"type":"string","pattern":"^[a-z0-9_]+$"}},"WatchId":{"name":"watch_id","in":"path","required":true,"example":"00000000-0000-4000-8000-000000000001","schema":{"type":"string","format":"uuid"}},"ClientId":{"name":"X-Price-Compare-Client-Id","in":"header","required":true,"description":"Stable server-side identifier used to isolate watchlists.","example":"sdk-client-001","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,80}$"}},"Range":{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","1y"],"default":"90d"}},"Goal":{"name":"goal","in":"query","required":false,"schema":{"type":"string","enum":["overall","best-price","travel","max-battery","camera"],"default":"overall"}},"Store":{"name":"store","in":"query","required":false,"example":"power.fi","schema":{"type":"string","minLength":2,"maxLength":120}}},"responses":{"BadRequest":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Authentication or client identification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Product or watch was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Temporary server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"ProductSpec":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string"},"value":{"type":"string"},"icon":{"type":"string"}}},"ProductSummary":{"type":"object","required":["canonical_product_id","product_name","brand","model","variant","match_confidence","min_price","store_count"],"properties":{"canonical_product_id":{"type":"string"},"product_name":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"variant":{"type":"string"},"image_path":{"type":"string"},"match_confidence":{"type":"number","minimum":0,"maximum":1},"min_price":{"type":"number","minimum":0},"store_count":{"type":"integer","minimum":0},"relevance_score":{"type":"number","minimum":0}}},"Product":{"type":"object","required":["canonical_product_id","product_name","brand","model","variant","category","ean","match_confidence"],"properties":{"canonical_product_id":{"type":"string"},"product_name":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"variant":{"type":"string"},"category":{"type":"string"},"ean":{"type":"string"},"match_confidence":{"type":"number","minimum":0,"maximum":1},"match_status":{"type":"string"},"image_path":{"type":"string"},"specs":{"type":"array","items":{"$ref":"#/components/schemas/ProductSpec"}},"comparison_name":{"type":"string"},"comparison_score":{"type":"number"},"comparison_badge":{"type":"string"},"comparison_summary":{"type":"string"}}},"Offer":{"type":"object","required":["store","item_price","delivery_cost","delivered_price","url","updated_at","availability"],"properties":{"store":{"type":"string"},"price":{"type":"number"},"item_price":{"type":"number"},"delivery_cost":{"type":"number"},"delivered_price":{"type":"number"},"url":{"type":"string","format":"uri"},"updated_at":{"type":"string","format":"date-time"},"availability":{"type":"string"},"availability_label":{"type":"string"},"stock_quantity":{"type":["integer","null"]},"delivery_estimate":{"type":["string","null"],"format":"date"},"delivery_label":{"type":"string"},"seller_score":{"type":["number","null"]},"return_days":{"type":["integer","null"]},"warranty_months":{"type":["integer","null"]},"data_quality":{"type":"number"},"decision_score":{"type":"integer"},"badge":{"type":"string"},"is_recommended":{"type":"boolean"},"is_lowest_item_price":{"type":"boolean"}}},"Decision":{"type":"object","required":["label","store","score","delivered_price","url","rationale","evaluated_offer_count","updated_at"],"properties":{"label":{"type":"string"},"store":{"type":"string"},"score":{"type":"integer"},"delivered_price":{"type":"number"},"url":{"type":"string","format":"uri"},"rationale":{"type":"string"},"lowest_item_price":{"type":"number"},"lowest_item_store":{"type":"string"},"evaluated_offer_count":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ProductComparison":{"type":"object","required":["canonical_product_id","product_name","product","offers"],"properties":{"canonical_product_id":{"type":"string"},"product_name":{"type":"string"},"product":{"$ref":"#/components/schemas/Product"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"decision":{"oneOf":[{"$ref":"#/components/schemas/Decision"},{"type":"null"}]}}},"SearchResponse":{"type":"object","required":["query","total","items"],"properties":{"query":{"type":"string"},"total":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}}}},"ComparisonProduct":{"type":"object","required":["canonical_product_id","comparison_name","best_offer"],"properties":{"canonical_product_id":{"type":"string"},"comparison_name":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"fit_score":{"type":"number"},"best_offer":{"$ref":"#/components/schemas/Offer"}},"additionalProperties":true},"ComparisonResponse":{"type":"object","required":["products"],"properties":{"products":{"type":"array","minItems":2,"maxItems":4,"items":{"$ref":"#/components/schemas/ComparisonProduct"}},"preference":{"type":"object","additionalProperties":true},"range":{"type":"string"},"goal":{"type":"string"}},"additionalProperties":true},"PricePoint":{"type":"object","required":["date","price"],"properties":{"date":{"type":"string","format":"date"},"price":{"type":"number"},"store":{"type":"string"}}},"PriceIntelligence":{"type":"object","required":["canonical_product_id","range","series","summary"],"properties":{"canonical_product_id":{"type":"string"},"range":{"type":"string"},"series":{"type":"array","items":{"type":"object","additionalProperties":true}},"summary":{"type":"object","additionalProperties":true}}},"StorePriceHistory":{"type":"object","required":["canonical_product_id","store","points","summary"],"properties":{"canonical_product_id":{"type":"string"},"store":{"type":"string"},"points":{"type":"array","items":{"$ref":"#/components/schemas/PricePoint"}},"summary":{"type":"object","additionalProperties":true}}},"PriceWatchInput":{"type":"object","required":["canonical_product_id","target_price","destination"],"properties":{"canonical_product_id":{"type":"string","pattern":"^[a-z0-9_]+$"},"target_price":{"type":"number","minimum":1,"maximum":1000000},"channel":{"type":"string","enum":["email"],"default":"email"},"destination":{"type":"string","format":"email","maxLength":254}}},"PriceWatchPatch":{"type":"object","minProperties":1,"properties":{"target_price":{"type":"number","minimum":1,"maximum":1000000},"destination":{"type":"string","format":"email","maxLength":254},"status":{"type":"string","enum":["active","paused"]}}},"PriceWatch":{"type":"object","required":["id","canonical_product_id","target_price","channel","destination","status","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"canonical_product_id":{"type":"string"},"target_price":{"type":"number"},"channel":{"type":"string","enum":["email"]},"destination":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","paused"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"product":{"oneOf":[{"$ref":"#/components/schemas/ProductSummary"},{"type":"null"}]},"current_price":{"type":["number","null"]},"target_reached":{"type":"boolean"}}},"WatchlistResponse":{"type":"object","required":["total","items"],"properties":{"total":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/PriceWatch"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Price Compare API key","description":"Server-side API key with explicit catalog, comparison, and watchlist scopes. Never expose the key in browser code."}}}}