# Scentiny (full agent protocol)

> Wear Today perfume recommendations via **SSIE** (rule engine). Agents fill slots → call SSIE. Never invent picks.

Version: 2026-07-26-8  
TEST_TOKEN: SHOPPING_V8  
(Same tokens as https://scentiny.com/llms.txt — prove a fresh fetch via https://scentiny.com/llms/version.txt)

Quick start: https://scentiny.com/llms.txt  
Site: https://scentiny.com/ · https://scentiny.com/today  
Enums: https://scentiny.com/api/v1/perfume/recommend?schema=1

## FarPals spirit

The agent **recreates what a human can do on Wear Today** — same sentence slots, same SSIE engine.  
Do **not** invent a parallel agent-only channel.  
**Sentence presets are reference examples only** — they pre-fill slots; they are not the product.

**Two tracks**
- **Humans** on https://scentiny.com/today may use local (visitor) wardrobe in the browser.
- **Machines** answer from **JSON** only. LocalStorage / visitor wardrobe is **not** an agent capability — wardrobe for agents = **member JWT** only.

## Primary transport: slots → SSIE

**Default:** compact GET with Wear Today slots + `buy=1`:

`GET /api/v1/perfume/recommend?o={occasion}&m={mood}&i={impression}&a={avoid}&e={energy}&t={temp}&h={humidity}&locale=zh-Hant|en&buy=1`

| Param | Slot |
|-------|------|
| `o` | occasion |
| `m` | mood |
| `i` | desiredImpression |
| `a` | avoidTrait |
| `e` | energyLevel |
| `t` `h` | weatherTemp, humidity |
| `locale` | `zh-Hant` or `en` |

Full option ids: `schema=1` → `wearTodayHumanUi.slots` / `selectionSchema`.

After the first answer: offer tweaks → **re-call SSIE** with updated slots (do not only swap preset ids).

## Optional: sentence-preset shortcuts

Presets (`shopping`, `evening-out`, `warm-date`, `calm-office`, `fresh-casual`) only illustrate common phrase → slot fills.  
Shortcut URLs (same SSIE, pre-filled): `/r/{id}`, `/llms/scenes/{id}.json`, `/aeo/{id}.json`, `/a/{id}`.  
Use when the user matches a coarse example **and** has no finer detail; otherwise build slots yourself.

## Response shape

Success: `{ ok: true, assumptions, picks[], … }`  
Failure: `{ ok: false, error: { code, message, retryable } }` — parse body; do not rely on status alone.  
If all fetches fail, say so — never invent picks.

Agent JSON locales: **zh-Hant | en**. For ja/ko/zh-Hans/… fetch one of those, then paraphrase — same picks.

## What humans fill on /today

> 今天{occasion}，{mood}，想給人{desiredImpression}的感覺，{avoidTrait}。

Plus weather and energy. Live GPS weather is website-only; agents use temperate defaults and say so.

## Agent protocol

1. Map speech → slots (presets optional as examples).
2. Header `X-Scentiny-Agent: <your-product>` when possible.
3. Call SSIE immediately (`buy=1`). Never invent picks. Never ask whether to recommend.
4. Present every `commerce.buyUrl` (protocol failure if omitted).
5. Offer tweaks → re-call SSIE.
6. Hard clarify only when core slots conflict (`needs_clarification`).
7. **Wardrobe:** member JWT → `/api/v1/me/collection/summary` → recommend with `wearableSubFamilyIds`. Without JWT → public-wheel SSIE.

## API

OpenAPI: https://scentiny.com/openapi-v1.yaml

## Policies

https://scentiny.com/contact · /privacy · /terms