What the partner API offers

Sniffopotamus holds the facts about perfumes: the brand, the name, the strength, the year, the perfumers, the brand's own words, and the note pyramid with a picture of every ingredient. The partner API is how a business puts those facts on its own site, app or shop.

It answers with the same card a person sees on sniffopotamus.com. Both are built by the same function, so your answer cannot drift from ours, and a correction reaches both at once.

New here? Go to Getting started. It takes you from signing in to a card on your own page.

What you can call today

Call	What it does	Costs
GET /api/partner/v1/whoami	Checks your key and shows today's counts.	Free
GET /api/partner/v1/capabilities	Tells your code what it may call, what each card field means, the answer codes and the rules.	Free
GET /api/partner/v1/fragrances/{id}/card	The full card for one perfume.	One call, only when a card is served

Every call is GET, from your server, to https://www.sniffopotamus.com, with your key as Authorization: Bearer <key>. The door sends no CORS headers, on purpose, so a browser cannot call it and your key never reaches a shopper's device.

What a card holds

Every example in these pages uses one perfume: Xerjoff, Casamorati - Casafutura, Eau de Parfum, id 03c188b7-74aa-469d-ae40-caa8c45673b7. It is public, its description is the brand's own words, and all ten of its notes have a picture. Shortened here to one note per stage, with some fields and most of the description left out:

{
  "ok": true,
  "status": "public",
  "card": {
    "id": "03c188b7-74aa-469d-ae40-caa8c45673b7",
    "name": "Casamorati - Casafutura",
    "strength": "Eau de Parfum",
    "year": 2021,
    "brand": { "id": "d9a4d53b-9d37-481e-a6f5-3d781b469bf6", "name": "Xerjoff", "slug": "xerjoff", "countryCode": "IT", "country": "Italy" },
    "perfumers": [],
    "tiers": [
      { "tier": "top", "heading": "Top", "notes": [{ "name": "Bergamot", "picture": "https://itelnlqvfovkxuxnwvyu.supabase.co/storage/v1/object/public/note-images/bergamot/white-botanical-watercolour-v1-be1c617b.png", "linked": true }] },
      { "tier": "heart", "heading": "Heart", "notes": [{ "name": "Rose", "picture": "https://itelnlqvfovkxuxnwvyu.supabase.co/storage/v1/object/public/note-images/rose/white-botanical-watercolour-v1-18fd2f98.png", "linked": true }] },
      { "tier": "base", "heading": "Base", "notes": [{ "name": "Sandalwood", "picture": "https://itelnlqvfovkxuxnwvyu.supabase.co/storage/v1/object/public/note-images/sandalwood/white-botanical-watercolour-v1-6b2d48fc.png", "linked": true }] }
    ],
    "families": [{ "name": "Woods, Aromatic, Green, Floral, Citrus" }],
    "relationships": [],
    "description": { "text": "Casafutura is a unique perfume that draws inspiration from the Futurist art movement. …", "brandWords": true },
    "availability": null
  }
}

The card answer has the whole answer and explains every field.

What is never in a card

• No prices, and no bottle photographs.
• No ratings, no reviews, and no men's or women's labels.
• No Fragrantica address, and no source or link saying where a fact was found.
• No label on the description. The words carry no "source:" line and no website's or shop's name, and your page must not add one.

These are also part of the terms you use cards under; see Rules and terms of use.

Build for a partial card

We hold 176,047 perfumes from 8,572 brands (counted 29 September 2026). Coverage is uneven, and a card leaves a block empty rather than refusing to appear:

A perfume has	Share
a year	73%
notes of any kind	85%
notes split into top, heart and base	68%
a description we may publish	72%
a named perfumer	34%
a recorded strength	28%

Show what is there, block by block. Hiding the whole card because one block is empty would leave most of your pages bare.

What is coming

None of these is built yet. capabilities lists each one under the name below with status: "planned", and it moves to live only when it works. The changelog announces each one as it arrives.

Coming	name in capabilities	What it will do
Search	search	Find a perfume's id from the words a person types.
Matching	match	Send your product list and get back matched ids. An unclear line stays unmatched for a person to choose; nothing is guessed.
Looks	looks	Your saved card designs (layout, what to show, where it goes), applied to what you fetch.
Pictures	picture	A finished card as a picture file, for posts, stories and listing images.
A command-line tool	cli	Cards, search and matching from a terminal or a script, with the same key and allowance.
A company login for AI assistants	mcp_company_login	Your organisation's AI assistant reading cards through our MCP server, on your business's allowance.
A website block	website_block	A ready-made block of HTML your server fetches and places in a page.
An email block	email_block	The same card, laid out for newsletters.
Change alerts	change_alerts	A message to your server when a card you hold has changed.
Social connections	connections	Send a post made from a card to your own Canva, Zernio or Mixpost account, always as a draft you approve there.
Build your perfume	build_your_perfume	A brand writes up a new perfume (name, strength, year, a pyramid from our ingredient library, its own words) and sends it to be published after our usual checks.

Until search and matching exist, you find ids by hand; see Getting started.

Prices

Prices are not published yet. The apps owned by Sniffopotamus's owner (ScentSell, NotRealSmart and Underground Parfums) are not charged. Every other business is by arrangement for now: email sniff@sniffopotamus.com. Whatever the arrangement, each business has a monthly allowance of cards; see Limits and caching.

How the API changes

From 29 September 2026, version 1 only grows. We may add fields, answer codes and endpoints, but we do not remove or rename a field, change what a field means, or change its type. A change that would break working code comes as a new version at a new address. Every change is announced in the changelog first. Write your code to ignore fields it does not know.

Where to go next

• Getting started: from signing in to a card on your page.
• The card answer: every field, with the full Casafutura card.
• Errors and refusals: every answer code and what to do.
• Limits and caching: your allowance, the ceilings, and the stored-copy rule.
• Rules and terms of use: what you may and may not do with cards and pictures.
• Test with your own app: ScentSell's integration, as a worked example.
• Changelog: what changed, and every correction to these pages.