/v1/search endpoint is the primary way to discover entities in the Noteboxd database by keyword. Whether you’re looking up a specific fragrance, exploring a brand’s catalog, or finding notes by name, a single search call returns ranked results across all entity types — or just the type you specify.
Basic Search
Pass your keyword to theq parameter to run a universal search across all entity types. Results are ranked by relevance and you can request up to 25 at a time.
type field so you can handle each kind appropriately in your application.
Filtering by Type
Use thetype parameter to restrict results to a single entity kind. This is especially useful when you already know what category you’re looking for and want cleaner, more predictable results.
The following example searches specifically for notes matching “rose”:
fragrance won’t surface brand or perfumer entries that happen to share the word.
Pagination and Limits
Thelimit parameter accepts any integer between 1 and 25. There is no offset-based pagination on the search endpoint itself — it is designed for relevance-ranked, top-N lookups.
If you need to page through a larger dataset (for example, all fragrances by a specific brand), use the /v1/fragrances listing endpoint, which supports cursor-based pagination. Use /v1/search for discovery, and the dedicated listing endpoints for exhaustive retrieval.
Using Search Results
The identifiers returned by search can be passed directly into other Noteboxd endpoints:- Fragrances return an
idfield (e.g."chanel-no-5"). Use this with/v1/fragrances/{id}to fetch the full profile, or with/v1/fragrances/{id}/similarto find related scents. - Brands, notes, and perfumers return a
slugfield (e.g."chanel"). Use this with the corresponding entity endpoints such as/v1/brands/{slug}or/v1/notes/{slug}.
id or slug → call the detailed endpoint. You won’t need to hardcode or pre-fetch any identifiers.
Each call to
/v1/search costs 1¢, regardless of how many results you request. The limit parameter does not affect the price.