Changelog

How the API changes

• Version 1 only grows, from 29 September 2026. We may add fields, answer codes and endpoints. We do not remove or rename a field, change what a field means, or change its type, within version 1.
• A breaking change comes as a new version at a new address (for example /api/partner/v2/…), never as a change to version 1.
• Every change is announced here first, newest first. A planned endpoint moves from planned to live in capabilities on the day it works, and is listed here.
• Write your code to ignore fields it does not know.

Dates are in Australian Eastern time.

30 September 2026

The API

• Removed: the label fields from the card. description.credit, description.url, sources, the words on every note, perfumer, family and link between perfumes, and availability.source (with availability.url) are no longer in the card answer. (availability.words, such as "No longer made", stays: it is the fact itself.) A card now carries facts only; where each fact came from stays in our database. None of these fields was ever for display. This removes fields within version 1, against the rule above; if your code reads any of them, treat each as absent. See The card answer.
• Changed: relationships lists only confirmed links. Dupe, "inspired by" and flanker links we have not yet checked no longer appear in the card answer, and a group left with no confirmed link is left out. With the basis words gone, an unchecked link could not be told from a checked one, so it is not sent. See Relationships.
• New: ETag and 304 Not Modified on the card. Every card answer carries an ETag. Send it back as If-None-Match and an unchanged card answers 304 with no body, and costs no call. See Limits and caching.

29 September 2026

The API

• One shape for every refusal. Every answer that is not a card is { "ok": false, "error": { "code", "message", "docs" } }. in_review and not_found keep their old status field too. Before this, error was a plain word and in_review and not_found had no error at all. This is the last change to version 1 that could break working code; see Errors and refusals for a reader that handles both.
• New: GET /api/partner/v1/capabilities. Tells your code what it may call today and what is planned, what each card field means, the answer codes and the rules. Free.
• whoami points on to capabilities and to these pages.
• Keys from the Builder Console. The owner of a business record creates, rotates and revokes its keys at sniffopotamus.com/dev/console, instead of asking us. A rotation is either "leaked" (the old key stops at once) or "routine" (the old key works until you stop it).
• Only a served card costs a call. An id that is not a fragrance id, a perfume held back, and a perfume we do not hold are checked before anything is counted, so they are free.
• The failed-attempt ceiling counts only failed keys. Requests with a valid key never count toward the 30-a-minute limit on a network address.
• Each key has its own ceiling of 1,200 requests a minute, above anything your business's ceilings let you reach, so it only affects a copied key.
• A fault on our side is never "wrong key". If we cannot read your account, the answer is 503 unavailable, not 401 unknown_key.

Corrections to these pages

The first version of these pages (21 September 2026) disagreed with what the API does in these places. Each is now fixed:

The old pages said	What is true
The card has concentration, family, perfumers as a list of names, notes.top / notes.heart / notes.base, and sources as an object	It has strength, families (a list of objects), perfumers (a list of objects), tiers (a list, each with a heading and notes), and sources as a list. See The card answer.
Every ingredient in the pyramid carries a picture and a description	Only notes linked to our ingredient library do. Others have a name only.
Render the source with each fact; a description from a website must be attributed to it	Descriptions carry no label of any kind, and neither should your page. Sources stay in our database.
A card answer carries an ETag, and If-None-Match gets a free 304	Neither exists yet. Keep a stored copy instead.
Keep a card for five minutes	One rule: serve a stored copy for 24 hours, keep serving it up to 7 days when we error or your allowance is out, and drop it at once on in_review or not_found. See Limits and caching.
The daily ceiling means you are done until tomorrow	It is a sliding 24 hours, and Retry-After says when to try again.
Every 429 counts as a refusal in your usage	Ceilings reached are not counted in your usage yet.
Nothing about a monthly allowance	Each business has one; when it is used up the answer is over_allowance until 00:00 UTC on the first of next month.
Keys are issued by hand	We set up your business record by hand; the owner then creates keys in the Builder Console.
A correction reaches you within five minutes	A correction reaches you the next time you refresh your stored copy, within 24 hours.

A newcomer's trial of the drafts of these pages, the same day, found more places where they disagreed with each other or said too little. Each is now fixed:

The drafts	Now
Said both "keep a card for five minutes" and "24 hours, 7 days"	One stored-copy rule, stated once on Limits and caching and followed by every example.
The first code example passed a fragrance id from the browser	Every example asks by your own product or listing id, looks up the Sniffopotamus id on your server, and keeps a stored copy.
Used a different perfume on each page	One worked example everywhere: Casafutura, 03c188b7-74aa-469d-ae40-caa8c45673b7.
Loaded the key two different ways	read -rs SNIFF_PARTNER_KEY everywhere; never a key typed on a command line.
Sent you to a business area for keys	Keys are created in the Builder Console at sniffopotamus.com/dev/console.
Did not say how setup works or what it costs	Sign in first; we set up the business record by hand; prices are not published yet. See Getting started.
Listed only some of what is planned	The full planned list, with each one's name in capabilities, is on What the partner API offers.
Did not say how to find ids	Today by hand on sniffopotamus.com/explore; matching is planned.
Did not say where access is switched on, or who can stop a leaked key	The switch sits on the owner's own account today; only the owner can rotate or revoke a key, or we can on request.
Had no terms of use, no versioning policy, no ids to test with, and no support contact	See Rules and terms of use, the top of this page, Testing each answer, and sniff@sniffopotamus.com.
Linked to pages that are for the Sniffopotamus team	These pages now link only to each other and to the app.

The catalogue counts in these pages were counted again on 29 September 2026: 176,047 perfumes from 8,572 brands.

28 September 2026

• description.credit is always null. A description carries no credit line, whatever its source. The field stays in the answer so code that reads it does not break.

26 September 2026

• Every live perfume in the catalogue is public. Since then no id has answered in_review, but your code must still handle it; see Errors and refusals.

21 September 2026

• The partner API opened with whoami and the card endpoint.