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

# Migrate from API v1

> Move an existing /v1 integration to Commercial API v2 before v1 closes on 31 December 2026.

v1 stays available until **31 December 2026**. After that date, v1 requests are no longer served. This guide covers what to change.

## 1. Accept the v2 terms

In the [developer portal](https://developers.noteboxd.com), accept the [v2 API terms](https://www.noteboxd.com/legal/api-terms) (version 2.0). Until you do, `/v2` calls return `403 TERMS_NOT_ACCEPTED`.

## 2. Keep your developer key

Existing developer keys (`nb_live_...`) work on v2. Do not reissue them unless you want to. Keep sending `Authorization: Bearer nb_live_...`.

Partner keys (`nb_partner_...`) do not work on `/v2`. Keep those integrations on `/v1` until you have a developer key, or contact us. MCP account keys (`pb_live_...`) are unchanged and still do not work on the commercial API.

## 3. Change the path prefix

The production host stays `https://api.noteboxd.com`. Replace `/v1` with `/v2` on every path, for example:

```bash theme={null}
# v1
curl "https://api.noteboxd.com/v1/fragrances/guerlain%2Fshalimar" \
  -H "Authorization: Bearer $NOTEBOXD_API_KEY"

# v2
curl "https://api.noteboxd.com/v2/fragrances/guerlain%2Fshalimar?view=basic" \
  -H "Authorization: Bearer $NOTEBOXD_API_KEY"
```

`https://noteboxd.com/api/v2` also serves the same API. Use `https://api.noteboxd.com/v2` as the canonical base URL.

## 4. Update identifiers and query shapes

* Fragrance records have an opaque `id` and a `slug` of the form `brand/name`. Either works in a path. Encode the slash: `guerlain%2Fshalimar`.
* `GET /v2/fragrances` requires at least one of `brand`, `family`, `note`, or `accord`. There is no `q` or `priceRange` filter. For keyword search, use `GET /v2/search`. A missing filter returns `400 FILTER_REQUIRED`.
* `GET /v2/fragrances/{id}` defaults to `view=detailed` (`$0.010`). Pass `view=basic` for a card at `$0.005`.
* List responses use `{ "data": [...], "pagination": { "nextCursor": "...", "limit": 20 } }`. Pass `pagination.nextCursor` as `cursor` for the next page.
* Search returns `{ "query": "...", "data": [...] }`, not a `results` array. Each hit has `type`, `id`, `name`, `subtitle`, `imageUrl`, and `score`. The `type` filter is `fragrances`, `brands`, `notes`, `perfumers`, or `all`. There is no `collections` type.
* Batch accepts up to **100** ids or slugs, and you pay only for records found: `$0.005` or `$0.010` each. The v1 batch price was a flat 25¢ for up to 50.
* Reviews are up to 5 of the most helpful published reviews, not a paged list of every review.

## 5. Adjust to v2 prices and plans

v2 charges the exact list price, with no 1¢ minimum. A `304 Not Modified` costs half. Monthly plans include usage, then a discount on prepaid overage. See [pricing and plans](https://docs.noteboxd.com/concepts/pricing.md) and the [v1 and v2 price table](https://docs.noteboxd.com/v1/overview.md).

On plans with a daily cap, read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Distinct-record errors use `DISTINCT_QUOTA_EXCEEDED`, not `RECORD_CAP_EXCEEDED`.

## 6. Handle signed image links

v2 catalogue `imageUrl` values on `img.noteboxd.com` include `exp` and `sig`, and expire at the end of your plan's catalogue window (3 days on Pay as you go, 7 on Starter, 14 on Growth, 30 on Scale, and by contract on Enterprise). Display the link as returned. Do not download or store the files, except under an Embedded Data License. Fetch the record again for a new link. See [caching and ETags](https://docs.noteboxd.com/concepts/caching-and-etags.md).

v1 image URLs are not signed this way.

## 7. Send ETags when you can

For endpoints that return an `ETag`, send `If-None-Match` on the next request. A `304` has no body and costs half the list price. Search is not eligible.

## Checklist

* [ ] v2 terms accepted in the portal
* [ ] Paths use `/v2`
* [ ] List filters, search `data` shape, and pagination object updated
* [ ] `view=basic` or `view=detailed` set where you care about price
* [ ] Image links displayed as returned, and refreshed with the record
* [ ] Error handling covers `TERMS_NOT_ACCEPTED`, `FILTER_REQUIRED`, `PLAN_UPGRADE_REQUIRED`, `DISTINCT_QUOTA_EXCEEDED`, and `AI_BUDGET_EXCEEDED`


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