{"openapi":"3.1.0","info":{"title":"Parfum Bible public read-only API","version":"1.0.0","description":"Published catalog data and exact verified retailer bottle variants. Null prices and availability make no current stock claim. No checkout, account or OPS access."},"servers":[{"url":"https://parfumbible.com"}],"paths":{"/api/agent/v1/search":{"get":{"operationId":"search_fragrances","description":"24 results per page; usable US pairings first.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120},"description":""},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"country","in":"query","schema":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"}}],"responses":{"200":{"description":"Public data; unknown values are null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Invalid arguments"},"404":{"description":"Unknown product"},"503":{"description":"Catalog temporarily unavailable"}}}},"/api/agent/v1/fragrances/{productId}":{"get":{"operationId":"get_fragrance","description":"Catalog details and exact verified variants.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":""},{"name":"country","in":"query","schema":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"}}],"responses":{"200":{"description":"Public data; unknown values are null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Invalid arguments"},"404":{"description":"Unknown product"},"503":{"description":"Catalog temporarily unavailable"}}}},"/api/agent/v1/offers":{"get":{"operationId":"get_verified_offers","description":"Original retailer tracking links; checkout at the retailer.","parameters":[{"name":"productId","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":""},{"name":"country","in":"query","schema":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"}}],"responses":{"200":{"description":"Public data; unknown values are null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Invalid arguments"},"404":{"description":"Unknown product"},"503":{"description":"Catalog temporarily unavailable"}}}},"/api/agent/v1/compare":{"get":{"operationId":"compare_fragrances","description":"Compare catalog-listed facts for 2–4 distinct IDs.","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","example":"27708,92816"},"description":"Comma-separated 2–4 distinct positive integers."},{"name":"country","in":"query","schema":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"}}],"responses":{"200":{"description":"Public data; unknown values are null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Invalid arguments"},"404":{"description":"Unknown product"},"503":{"description":"Catalog temporarily unavailable"}}}}},"components":{"schemas":{"Result":{"type":"object","required":["apiVersion","generatedAt","country","disclosure"],"properties":{"apiVersion":{"const":"1"},"generatedAt":{"type":"string","format":"date-time"},"country":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"},"disclosure":{"type":"string"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"fragrance":{"type":"object"},"fragrances":{"type":"array","items":{"type":"object"}},"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"const":24},"sharedListedNotes":{"type":"array","items":{"type":"string"}}}},"Variant":{"type":"object","required":["variantId","productId","concentration","sizeLabel","offers"],"properties":{"variantId":{"type":"string","description":"Stable ID for catalog product, concentration and selected size label; not a GTIN."},"productId":{"type":"integer"},"concentration":{"type":"string"},"sizeLabel":{"type":"string"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}},"Offer":{"type":"object","required":["id","retailer","url","affiliate","browseOnly","price","availability"],"properties":{"id":{"type":"string"},"retailer":{"type":"string"},"url":{"type":"string","format":"uri"},"affiliate":{"type":"boolean"},"linkRel":{"type":"string"},"country":{"type":"string","enum":["US","GB","CA","AU","KR","OTHER"],"default":"US"},"browseOnly":{"type":"boolean"},"availability":{"type":["string","null"]},"availabilityCheckedAt":{"type":["string","null"],"format":"date-time"},"identityCheckedAt":{"type":"string","format":"date-time"},"sourceUrl":{"type":["string","null"],"format":"uri"},"price":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"referencePrice":{"type":["object","null"],"properties":{"amount":{"type":"number"},"type":{"enum":["regular","msrp"]}}}}}}}}},"x-mcp":{"url":"https://parfumbible.com/mcp","transport":"Streamable HTTP","protocolVersion":"2025-11-25","tools":["search_fragrances","get_fragrance","compare_fragrances","get_verified_offers"]}}