Skip to main content
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, accept the v2 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:
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 and the v1 and v2 price table. 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. 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. 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