> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noteboxd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search the Noteboxd API: Fragrances, Brands, and Notes

> Use the Noteboxd universal search endpoint to find fragrances, brands, notes, perfumers, and collections by keyword across the full database.

The `/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 the `q` 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.

```bash theme={null}
curl -G https://api.noteboxd.com/v1/search \
  -H "Authorization: Bearer nb_live_YOUR_KEY" \
  --data-urlencode "q=Chanel No 5" \
  --data-urlencode "limit=5"
```

```json theme={null}
{
  "results": [
    {
      "type": "fragrance",
      "id": "chanel-no-5",
      "name": "No 5",
      "brand": "Chanel"
    },
    {
      "type": "brand",
      "slug": "chanel",
      "name": "Chanel"
    }
  ]
}
```

Notice that the response mixes entity types. Each result includes a `type` field so you can handle each kind appropriately in your application.

## Filtering by Type

Use the `type` 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.

| Type | Description |
| - | - |
| `fragrance` | Scent products from any brand |
| `brand` | Fragrance houses and perfume labels |
| `note` | Olfactory ingredients (e.g. rose, oud, bergamot) |
| `perfumer` | Creators and nose artists |
| `collection` | Curated lists of fragrances |

The following example searches specifically for notes matching "rose":

```bash theme={null}
curl -G https://api.noteboxd.com/v1/search \
  -H "Authorization: Bearer nb_live_YOUR_KEY" \
  --data-urlencode "q=rose" \
  --data-urlencode "type=note" \
  --data-urlencode "limit=10"
```

Filtering by type also tends to improve result relevance — a search for "Sauvage" filtered to `fragrance` won't surface brand or perfumer entries that happen to share the word.

## Pagination and Limits

The `limit` 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 `id` field (e.g. `"chanel-no-5"`). Use this with `/v1/fragrances/{id}` to fetch the full profile, or with `/v1/fragrances/{id}/similar` to find related scents.
* **Brands, notes, and perfumers** return a `slug` field (e.g. `"chanel"`). Use this with the corresponding entity endpoints such as `/v1/brands/{slug}` or `/v1/notes/{slug}`.

This means a typical workflow looks like: search → grab the `id` or `slug` → call the detailed endpoint. You won't need to hardcode or pre-fetch any identifiers.

<Tip>
  Looking for popular fragrances without a specific query? Check out the [trending endpoint](/api-reference/search/trending) for pre-built trending data that requires no search term at all.
</Tip>

<Note>
  Each call to `/v1/search` costs **1¢**, regardless of how many results you request. The `limit` parameter does not affect the price.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.