canonical: https://jentic.com/apis/noteboxd.com/noteboxd # Noteboxd Public API The Noteboxd Public API returns fragrance, brand, note, perfumer, and chart data from the Noteboxd fragrance community. A client can search across fragrances, notes, brands, perfumers, and collections, filter fragrances by brand, note, family, or price range, and open a full profile with its notes, accords, score, and perfumer. It also serves community reviews, aggregate wearing data by season and mood, similar fragrances by accord profile, and chart leaderboards. AI-generated comparisons of two fragrances and digests of a fragrance's reviews are available, and each call is billed per endpoint against a prepaid balance. ## For AI agents Search fragrances, notes, brands, and perfumers, read full scent profiles and community reviews, find similar fragrances, and compare two fragrances from Noteboxd data. ## Scope Does not sell fragrances, process orders, or post reviews. Use for reading Noteboxd fragrance, brand, note, perfumer, review, and chart data only. ## Capabilities - Search across fragrances, notes, brands, perfumers, and collections with one query on GET `/v1/search` - Filter fragrances by brand, note, family, and a priceRange of BUDGET, MIDRANGE, or PREMIUM - Read a fragrance's full profile with notes, accords, score, and perfumer - Find similar fragrances by accord profile and read aggregate wearing data by season and mood - Compare two fragrances side by side or get a digest of a fragrance's community reviews - Fetch up to 50 fragrances in one call with the batch endpoint - Browse chart leaderboards and trending queries, fragrances, and notes ## Use cases ### AI fragrance recommendation assistant An AI shopping assistant helps a user find a new scent based on one they already own. Through Jentic the agent searches for 'find fragrances similar to one I like', gets the Noteboxd similar-fragrances operation with its input schema, and calls it for the user's fragrance id. It then reads each candidate's profile and wearing stats so its suggestions rest on real notes, accords, and seasons rather than guesses. Example prompt: Call GET `/v1/search` with q=Baccarat Rouge 540 and type=fragrance to get its id, call GET `/v1/fragrances/{id}/similar` with limit=5, then call GET `/v1/fragrances/{id}/wearing-stats` for each result and recommend the ones worn in winter ### Fragrance filtering by note and budget A retail or content site wants listings of fragrances that match a note, family, or budget. GET `/v1/fragrances` filters by brand, note, family, and priceRange with cursor pagination, and POST `/v1/fragrances/batch` returns up to 50 fragrance profiles in a single call once the ids are known. The full profile carries notes, accords, score, and perfumer for each item. Example prompt: Call GET `/v1/fragrances` with note=vanilla, family=amber, and priceRange=MIDRANGE, collect the ids, then call POST `/v1/fragrances/batch` with those ids to load the full profiles ### Review summaries and head-to-head comparisons A buyer choosing between two scents wants the trade-offs in plain language. GET `/v1/fragrances/compare` takes two fragrance ids, a and b, and returns shared and distinct notes, scores, and a grounded synthesis, while GET `/v1/fragrances/{id}/review-digest` summarises a fragrance's community reviews. These are the higher-priced endpoints, so an agent calls them only once it has narrowed the choice. Example prompt: Call GET `/v1/fragrances/compare` with a and b set to two fragrance ids, then call GET `/v1/fragrances/{id}/review-digest` for the higher-scoring one and report the shared notes and the review summary ### Brand, perfumer, and note research A writer or analyst researching a house or a perfumer needs their full range in one place. GET `/v1/brands/{slug}` returns a brand profile with top fragrances and GET `/v1/brands/{slug}/fragrances` pages through every fragrance from the brand, GET `/v1/perfumers/{slug}` lists a perfumer's top creations, and GET `/v1/notes/{slug}` shows the fragrances that feature a note most. Example prompt: Call GET `/v1/perfumers/{slug}` for a perfumer, then call GET `/v1/notes/{slug}` for the most frequent note in their top creations and list the other fragrances that feature it ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/search` | Universal cross-entity search | | GET | `/v1/fragrances` | Search and filter fragrances | | GET | `/v1/fragrances/{id}` | Get a full fragrance profile | | GET | `/v1/fragrances/{id}/similar` | Find similar fragrances | | GET | `/v1/fragrances/compare` | Compare two fragrances | | GET | `/v1/fragrances/{id}/review-digest` | Digest of community reviews | | POST | `/v1/fragrances/batch` | Get up to 50 fragrances | | GET | `/v1/charts/{slug}` | Get a chart leaderboard | ## Key resources - **Fragrances** — Profiles with notes, accords, score, perfumer, reviews, wearing stats, and similar fragrances - **Brands and perfumers** — Profiles with top fragrances and paginated brand fragrance lists - **Notes and accords** — Note profiles by family with their top fragrances, plus the accord list - **Charts and trending** — Chart leaderboards and trending queries, fragrances, and notes ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 88 / 100 - **Maturity:** AI-Ready - **Dimensions:** - Foundational Compliance: 74 / 100 - Developer Experience & Jentic Compatibility: 100 / 100 - AI-Readiness & Agent Experience: 100 / 100 - Agent Usability: 94 / 100 - Security: 100 / 100 - AI Discoverability: 60 / 100 - **View full report:** https://jentic.com/apis/noteboxd.com/noteboxd/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Noteboxd by hand means sending a bearer project key, tracking per-endpoint pricing against a prepaid balance, and paging fragrance lists by cursor. Through Jentic you install once, import Noteboxd from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Each Noteboxd operation has its own URL path, such as `/v1/fragrances/{id}/similar` or `/v1/fragrances/compare`, so a rule can bound your agent to the operations its task needs. You choose which ones it may call, so the higher-priced batch and enrich POSTs are not included unless you add them. - **Credential handling:** Your Noteboxd API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find fragrances similar to one I like' or 'compare two fragrances', and Jentic returns the matching Noteboxd operation with its input schema, including parameters like note, family, and priceRange, so the agent calls the right endpoint directly. ## Related APIs - **Shopify API** — Storefront, product, and order management for online shops - **Etsy API** — Marketplace listings and shop management for independent sellers - **Reddit API** — Community posts and comments across subreddits ## FAQ ### What authentication does the Noteboxd Public API use? Per its OpenAPI spec, the Noteboxd Public API uses HTTP bearer authentication with a project API key in the nb_live_ format, issued from the Noteboxd developer portal and sent as Authorization: Bearer. Through Jentic the key is held by your own instance and injected at call time, so the agent never sees it. ### How is the Noteboxd Public API priced? Calls are billed per endpoint against a prepaid balance. The spec lists most lookups at 1 cent per call, similar fragrances and wearing stats at 2 cents, compare at 3 cents, review digests at 5 cents, enrich at 10 cents, and the batch endpoint at 25 cents per call. ### What are the rate limits for the Noteboxd Public API? The spec says calls share a per-account daily rate-limit pool and responses carry X-RateLimit-Limit headers, but it does not state a fixed number. Check the Noteboxd developer documentation at https://www.noteboxd.com/developers for your account's current limit. ### Can I get everything about a fragrance in one call with the Noteboxd Public API? Yes. POST `/v1/fragrances/enrich` takes a required id and returns notes, accords, reviews, and similar fragrances together, with optional similarLimit and reviewLimit fields. For several fragrances at once, POST `/v1/fragrances/batch` accepts up to 50 ids. ### How do I find similar fragrances through Jentic? Search Jentic for 'find fragrances similar to one I like', load the Noteboxd similar-fragrances operation, and call GET `/v1/fragrances/{id}/similar` with the fragrance id and a limit. Use GET `/v1/search` first if you only have the name. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Is there a Noteboxd MCP server? You do not need an MCP server to give your agent Noteboxd. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the search, profile, and review operations it needs on demand. ### Can I limit what my agent is allowed to do with the Noteboxd Public API? Yes. Because every call draws on your prepaid balance, write a rule that allows the 1-cent lookups such as GET `/v1/search` and GET `/v1/fragrances/{id}` and leaves out POST `/v1/fragrances/batch` and POST `/v1/fragrances/enrich.` The agent can still search and read profiles, and the calls it makes are logged for review.