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 stayshttps://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
idand aslugof the formbrand/name. Either works in a path. Encode the slash:guerlain%2Fshalimar. GET /v2/fragrancesrequires at least one ofbrand,family,note, oraccord. There is noqorpriceRangefilter. For keyword search, useGET /v2/search. A missing filter returns400 FILTER_REQUIRED.GET /v2/fragrances/{id}defaults toview=detailed($0.010). Passview=basicfor a card at$0.005.- List responses use
{ "data": [...], "pagination": { "nextCursor": "...", "limit": 20 } }. Passpagination.nextCursorascursorfor the next page. - Search returns
{ "query": "...", "data": [...] }, not aresultsarray. Each hit hastype,id,name,subtitle,imageUrl, andscore. Thetypefilter isfragrances,brands,notes,perfumers, orall. There is nocollectionstype. - Batch accepts up to 100 ids or slugs, and you pay only for records found:
$0.005or$0.010each. 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. A304 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.
6. Handle signed image links
v2 catalogueimageUrl 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 anETag, 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
datashape, and pagination object updated -
view=basicorview=detailedset 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, andAI_BUDGET_EXCEEDED