{ "openapi": "3.1.0", "info": { "title": "ScentPulse API", "description": "Fragrance intelligence for perfume collectors, dupe-hunters, and blind-buyers. All endpoints require x402 payment (USDC on Base mainnet, or Solana USDC-SPL) via the PAYMENT-SIGNATURE header.", "version": "1.0.0", "contact": { "url": "https://scentpulse-xi.vercel.app" } }, "servers": [ { "url": "https://scentpulse-xi.vercel.app" } ], "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 payment signature. Send a GET request without this header to receive a 402 with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header." } } }, "paths": { "/api/scent/note-profile": { "get": { "summary": "Fragrance note-profile lookup", "description": "Note pyramid (top/middle/base), accord breakdown, molecule-level odor descriptors, who it suits, and occasion/climate fit for any fragrance.", "operationId": "noteProfile", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Fragrance name" }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Note profile" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand" } }, "/api/scent/batch-check": { "get": { "summary": "Batch/lot code freshness decoder", "description": "In-house deterministic decoder covering Coty, Estee Lauder-group, Chanel, LVMH/Dior-group, and L'Oreal Luxe batch-code formats. Returns estimated production date/range and a freshness verdict with an explicit confidence tier \u2014 never false precision.", "operationId": "batchCheck", "parameters": [ { "name": "brand", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Decode result" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/scent/dupe-match": { "get": { "summary": "Dupe/clone finder", "description": "Ranked clone/dupe candidates from Lattafa, Armaf, Alexandria Fragrances, Dossier, ALT and the wider inspired-by ecosystem, with note-similarity scoring and honest longevity/quality trade-offs.", "operationId": "dupeMatch", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "budget", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dupe matches" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.15, "x-agent-use-case": "on-demand" } }, "/api/scent/blind-buy-risk": { "get": { "summary": "Blind-buy risk score", "description": "Composite risk score for buying a fragrance unsniffed \u2014 polarizing notes, review-sentiment spread, batch variation, reformulation exposure, discontinuation risk, and counterfeit prevalence.", "operationId": "blindBuyRisk", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "price_paid_usd", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risk score" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.12, "x-agent-use-case": "on-demand" } }, "/api/scent/reformulation-check": { "get": { "summary": "Reformulation checker", "description": "Has this fragrance been reformulated? IFRA-amendment-driven changes and community-documented vintage-vs-current differences.", "operationId": "reformulationCheck", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "batch_year_hint", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reformulation status" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.12, "x-agent-use-case": "on-demand" } }, "/api/scent/allergen-check": { "get": { "summary": "EU allergen context check", "description": "Context on the EU Regulation 2023/1545 80-substance mandatory allergen labeling list, likely allergen families for a fragrance/ingredient, and the live 31 July 2026 sell-off deadline countdown.", "operationId": "allergenCheck", "parameters": [ { "name": "fragrance_or_ingredient", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "ingredient_list", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Allergen context" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/scent/occasion-match": { "get": { "summary": "Occasion/season/climate fragrance matcher", "description": "Recommendations by occasion, season, climate, age, and budget \u2014 including hot-climate projection/longevity guidance for Gulf, Southeast Asia, and Latin America buyers.", "operationId": "occasionMatch", "parameters": [ { "name": "occasion", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "climate", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "age_range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "budget_usd", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recommendations" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/scent/price-per-ml": { "get": { "summary": "Price-per-ml value optimizer", "description": "Normalizes a fragrance's price across full bottles, gift sets, decants, and travel sprays into $/ml, surfacing the cheapest legitimate way to try or own it.", "operationId": "pricePerMl", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Price-per-ml breakdown" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand" } }, "/api/scent/attar-navigator": { "get": { "summary": "Middle Eastern attar/oud navigator", "description": "Attar/oud/CPO house intelligence for Western buyers \u2014 Ajmal, Rasasi, Swiss Arabian, Al Haramain, Arabian Oud \u2014 with a format primer and entry picks.", "operationId": "attarNavigator", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "budget_usd", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "experience_level", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attar/oud guidance" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/scent/discontinued-watch": { "get": { "summary": "Discontinuation watch", "description": "Signal-based discontinuation status (stock-outs, forum chatter, resale price trend), act-now guidance, and succession picks.", "operationId": "discontinuedWatch", "parameters": [ { "name": "fragrance", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discontinuation status" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/scent/collection-value": { "get": { "summary": "Collection valuation", "description": "Realistic resale/collector value estimate for one or more bottles, factoring discontinued/vintage status, batch desirability, and fill level.", "operationId": "collectionValue", "parameters": [ { "name": "bottles", "in": "query", "required": true, "schema": { "type": "string" }, "description": "URL-encoded JSON array of bottle objects" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Valuation" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.15, "x-agent-use-case": "on-demand" } }, "/api/scent/layering-guide": { "get": { "summary": "Fragrance layering guide", "description": "Layering combinations that work, application order, and resulting character, with Gulf attar/oud and Korean (K-fragrance) layering context.", "operationId": "layeringGuide", "parameters": [ { "name": "fragrances", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated fragrance names" }, { "name": "style_goal", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Layering guide" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } } } }