{"openapi":"3.1.0","info":{"title":"Zelos Price API","version":"2026-11-01","description":"Fitness equipment, sportswear, and training gear compared across retailers.\n\nOutbound offer URLs are affiliate links. Ranking is by price, never commission. See https://zelos.devilabs.dev/disclosure","contact":{"email":"zelos@devilabs.dev"}},"servers":[{"url":"https://zelos.devilabs.dev"}],"tags":[{"name":"keys","description":"Free key issuance"},{"name":"products","description":"Search and retrieve products"},{"name":"meta","description":"Health and diagnostics"}],"paths":{"/api/v1/keys":{"post":{"tags":["keys"],"summary":"Issue a free API key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Key issued. Shown once.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"rate_limit":{"type":"integer"}}}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me":{"get":{"tags":["keys"],"summary":"Describe the calling key","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"}],"responses":{"200":{"description":"Key info and remaining quota"},"401":{"description":"Unauthorized"}}}},"/api/v1/search":{"post":{"tags":["products"],"summary":"Search products","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":300},"image_url":{"type":"string","format":"uri"},"limit":{"type":"integer","minimum":1,"maximum":30,"default":10},"mode":{"type":"string","enum":["default","agentic"]}}}}}},"responses":{"200":{"description":"Products with offers","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"count":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/product/{product_id}":{"get":{"tags":["products"],"summary":"Retrieve a product","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"currency","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/product/{product_id}/offers":{"get":{"tags":["products"],"summary":"Merchant offers for a product, cheapest first","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"title":{"type":"string"},"currency":{"type":"string"},"best_price":{"type":"number"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}}}}}}}},"/api/v1/product/{product_id}/history":{"get":{"tags":["products"],"summary":"90-day price history","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Price history"}}}},"/api/v1/similar":{"post":{"tags":["products"],"summary":"Similar products","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id"],"properties":{"product_id":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":30}}}}}},"responses":{"200":{"description":"Products"}}}},"/api/v1/categories":{"get":{"tags":["products"],"summary":"Resolve a phrase to a category slug","security":[{"apiKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Free API key from POST /api/v1/keys"},{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Categories"}}}},"/api/v1/diagnostics":{"post":{"tags":["meta"],"summary":"Opt-in redacted error report","parameters":[{"name":"x-diagnostics-consent","in":"header","required":true,"schema":{"type":"string","enum":["opt-in"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"string"},"http_status":{"type":"integer"},"error_code":{"type":"string"},"message":{"type":"string","maxLength":512},"runtime":{"type":"string"},"sdk_version":{"type":"string"},"retryable":{"type":"boolean"},"occurred_at":{"type":"string"}}}}}},"responses":{"202":{"description":"Accepted"}}}},"/api/v1/health":{"get":{"tags":["meta"],"summary":"Liveness","responses":{"200":{"description":"ok"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Price":{"type":"object","properties":{"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":["number","null"]}}},"Offer":{"type":"object","properties":{"domain":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"availability":{"type":"string","enum":["InStock","OutOfStock"]},"condition":{"type":["string","null"]},"url":{"type":"string","description":"Affiliate link. Fetch fresh before display; do not cache."}}},"Product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"description":{"type":["string","null"]},"image":{"type":["string","null"]},"category":{"type":["string","null"]},"best_price":{"type":["number","null"]},"currency":{"type":"string"},"merchant_count":{"type":"integer"},"price_spread":{"type":"number"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"attributes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}