> ## 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.

# Caching, ETags, and image links

> How long you can cache v2 responses, what a 304 costs, and the rules for signed image links.

Responses are private to your account. Cache them only for as long as the windows below allow. Where the endpoint supports it, the response also includes an `ETag` tied to your account.

## Catalogue data

Fragrances, brands, perfumers, notes, and accords, including list and batch endpoints, can be cached for as long as your plan allows:

| Free | Pro and Pay as you go | Starter | Growth | Scale | Enterprise |
| - | - | - | - | - | - |
| 24 hours | 3 days | 7 days | 14 days | 30 days | By contract (30 days if the contract does not say) |

## Image links

Image links are for showing images in your app or site, not for downloading or storing them on a server. The only exception is an [Enterprise Embedded Data License](https://docs.noteboxd.com/concepts/pricing.md). Use each link exactly as returned, including its `exp` and `sig` parameters, and load it in a page or app view.

A signed link looks like this:

```
https://img.noteboxd.com/f/guerlain/shalimar-eau-de-toilette.webp?exp=1770000000&sig=…
```

Each link expires when your plan's catalogue window above ends (on Enterprise, the window in your contract, or 30 days if it does not say). To keep showing an image, fetch the record again and use the new link. Links stay the same for every call made on the same UTC day, so browsers can cache the images. Embeds on your own pages keep working until the link expires.

## Data that changes often

These windows are the same on every plan:

| Data | Endpoints | Cache for up to |
| - | - | - |
| AI results and similar fragrances | `review-digest`, `compare`, `similar`, `enrich` | 24 hours |
| Charts and reviews | `charts`, `charts/{slug}`, `reviews` | 6 hours |
| Wearing stats and votes | `wearing-stats` | 1 hour |
| Trending | `trending` | 30 minutes |
| Search | `search` | Do not cache |

When a cached response reaches the end of its window, delete it or revalidate it.

## Revalidating with an ETag

Send the `ETag` you saved in an `If-None-Match` header. If nothing changed, you get `304 Not Modified` with no body, at **half the list price**. If the 304 is paid from your prepaid balance, your plan's discount applies on top: 55% off on Starter, 65% on Growth, and 75% on Scale. The total discount never goes above 90%.

Search is not eligible for a `304`.

## Keeping data longer

On self-serve plans, cache only within these windows. You can keep bare `id` and `slug` values in your own records for as long as you like. Keeping catalogue data permanently, for example to seed your own product database or run your own search over Noteboxd fields, needs an **Enterprise Embedded Data License**. Email [api@noteboxd.com](mailto:api@noteboxd.com).


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