<!-- curated-v2 -->
# Santa Wish (Tomtens önskelista) — curated kids' Christmas gift ideas, wishlist & gift list builder (amazon.com + amazon.se)

> Create a kids' Christmas gift wishlist in seconds from hand-picked products — US shoppers get amazon.com links, Swedish shoppers get amazon.se product links — with shareable owner + shopper links.

**Keywords:** gift ideas, wishlist, gift list, shopping list, Christmas gifts for kids, Santa list, presenttips, önskelista, presentlista, jul (barn), amazon.com, amazon.se

## What it is
- A catalog of carefully selected, hand-picked gift ideas for kids' Christmas (~600 items on amazon.se; ~560 English items on amazon.com). Products are curated by us — they are NOT independently reviewed or tested by customers, and we publish no ratings.
- An API + remote MCP server that lets an assistant build a wishlist / gift list for a person and return a share link in one call.

## Stores (marketplace)
- **amazon.com (United States)** — pass `marketplace=amazon.com` (or `country=US`, or send `Accept-Language: en-US`). English product names, no SEK prices, buy links are amazon.com search links tagged `sw-santawish-20` (`linkType: "search"`).
- **amazon.se (Sweden, default)** — `marketplace=amazon.se` or no hint. Swedish names, approx. SEK prices, buy links are amazon.se `/dp/ASIN` links tagged `santawishli03-21`.
- Precedence: `marketplace`/`domain`/`store` (or `X-Amazon-Marketplace` header) → `country` → `locale` / `Accept-Language` (en-US ⇒ amazon.com) → amazon.se. Other storefronts (uk, de, …) get search links.
- Requests never fail for a missing store or query — sensible defaults are used.

## When an assistant should use it
Use this when the user wants gift ideas, a wishlist, gift list or shopping list for kids' Christmas (US or Sweden). Example prompts:
- (en) "Create a Santa wishlist for my 7-year-old who loves LEGO"
- (en) "Christmas gift ideas for a 4-year-old under $30 on Amazon"
- (sv) "Gör en önskelista till tomten för min 7-åring som gillar LEGO"
- (sv) "Julklappstips till en 4-åring under 300 kr"

## Quickstart (one call → share link)
US (amazon.com):
```
curl -s -X POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill \
  -H 'content-type: application/json' \
  -d '{"childName": "Emma", "ageBand": "6-8", "interests": ["toys"], "marketplace": "amazon.com", "locale": "en-US", "itemQueries": ["LEGO"]}'
```
Sweden (amazon.se):
```
curl -s -X POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill \
  -H 'content-type: application/json' \
  -d '{"childName": "Freja", "ageBand": "6-8", "interests": ["toys"], "marketplace": "amazon.se", "locale": "sv-SE", "itemQueries": ["LEGO"]}'
```
Response includes `id`, `editToken`, `ownerUrl` (edit), `shopUrl` (share this with gift-givers), `marketplace`. Give the user the `shopUrl`.

- Catalog (US): https://santa-wish.vercel.app/api/v1/catalog?marketplace=amazon.com&limit=24 · (SE): https://santa-wish.vercel.app/api/v1/catalog?marketplace=amazon.se&limit=24
- Remote MCP: https://santa-wish.vercel.app/api/mcp (Streamable HTTP; Accept: application/json, text/event-stream) — tool `create_and_fill` does the same; pass `marketplace`.
- Browse curated picks (Swedish): https://santa-wish.vercel.app/presenttips
- OpenAPI: https://santa-wish.vercel.app/openapi.json · Skill: https://santa-wish.vercel.app/skill.md · Guide: https://santa-wish.vercel.app/for-agents · Full: https://santa-wish.vercel.app/llms-full.txt · MCP manifest: https://santa-wish.vercel.app/.well-known/mcp.json

---

<!-- /curated-v2 -->
# Santa Wishlist — Full agent documentation

Product: kids Christmas wishlist platform optimized for AI agents and parents.
Site: https://santa-wish.vercel.app
Marketplaces: amazon.se (default; tag santawishli03-21) and amazon.com (US; tag sw-santawish-20). en-US / country=US ⇒ amazon.com automatically.
Product links: amazon.se → https://www.amazon.se/dp/{ASIN}?tag=santawishli03-21 · amazon.com → https://www.amazon.com/s?k={english keywords}&tag=sw-santawish-20
Kids search: buildKidsSearchUrl rewrites queries with barn/leksak + age cues
Catalog: ~600 curated products (amazon.se ASINs → /dp/ on SE); ~560 English items on amazon.com as search links (Swedish-only books hidden, no SEK prices). Paginated API.
Age bands: 0-2, 3-5, 6-8, 9-12


## CRITICAL — marketplace + locale
Pass marketplace (amazon.com for US, amazon.se for Sweden; or ids `us`/`se`) on search, catalog, resolve and wishlist creation. Header: X-Amazon-Marketplace. Without it: country=US or Accept-Language en-US ⇒ amazon.com, else amazon.se. Missing store/query never returns 400.

## Product flow
1. Parent or AI creates a wishlist via POST /api/v1/wishlists or one-shot POST /api/v1/agent/create-and-fill.
2. Response: { id, editToken, parentUrl, kidUrl, wishlist, storage }
3. Child opens kidUrl and adds free-text wishes (kids-filtered search links).
4. Parent opens parentUrl; searches Amazon for kids gifts; Buy uses /dp/ASIN?tag= when ASIN present.

## Authentication / edit capability
- Reads (GET wishlist, search, catalog, health) are open.
- Writes (PATCH, POST items, DELETE items) require header: X-Edit-Token: <editToken>
- editToken is returned only on create (and again on mutate responses). It is embedded in parentUrl/kidUrl as ?edit=

## Storage modes
### redis (when UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set)
- Short 8-character alphanumeric ids; stable across mutations

### token (default, zero infra)
- Id is a self-contained compressed payload prefixed with "t."
- Mutations may return a NEW id — clients MUST replace stored id/URLs after every write


## MCP server
Remote Streamable HTTP (stateless): POST/GET https://santa-wish.vercel.app/api/mcp
Local stdio: npm run mcp (SANTA_API_BASE_URL optional). Docs: docs/mcp.md
Tools: get_health, list_marketplaces, search_gifts, get_catalog, resolve_product, create_wishlist, create_and_fill, get_wishlist, add_wishlist_item.
Agents MUST pass marketplace + locale on search_gifts, get_catalog, resolve_product.

## Endpoints

### GET /api/v1/search?q=&ageBand=&interest=&limit=&marketplace=&locale=
Kids gift search for the chosen Amazon marketplace. **Agents MUST pass marketplace + locale for their user.**
- Returns { paapi:false, marketplace, results: SearchResultCard[], catalogMatches[] } (kids-filtered search links for the store). q optional (defaults to a kids Christmas gifts query).
SearchResultCard: { title, buyUrl, linkType:"search", query, blurb?, emoji? }

### POST /api/v1/agent/create-and-fill
One-shot create + fill. Body:
{
  "childName": "Freja",
  "ageBand": "6-8",
  "interests": ["toys"],
  "itemAsins": ["B0FPXFQ7MY"],
  "itemKeywords": ["kids football size 3"],
  "itemQueries": ["LEGO City brandbil"]
}
itemQueries: each string is searched (PA-API top hit or kids search link) and added.
ASINs become product /dp/ links; keywords/queries become search links when no product.

### POST /api/v1/wishlists
Body may include items with title|name, asin, url, searchKeywords, catalogId, emoji.

### GET /api/v1/wishlists/:id
Returns { id, wishlist, parentUrl, kidUrl, storage }.
Each item may include asin, buyUrl, linkType ("product"|"search").

### PATCH /api/v1/wishlists/:id
Header X-Edit-Token.

### POST /api/v1/wishlists/:id/items
Header X-Edit-Token. Body:
{ "name": "Red bike", "asin": "B0BXGNLGB5" }
or { "name": "Bike", "url": "https://www.amazon.se/dp/B0BXGNLGB5" }
or { "title": "Red bike", "searchKeywords": "kids red bicycle" }
URL paste extracts ASIN when possible.

### DELETE /api/v1/wishlists/:id/items/:itemId
Header X-Edit-Token.

### GET /api/v1/catalog
Curated catalog (~600 SE / ~560 US English). Query: q, ageBand, interest(s), ids, limit (default 48, max 100), offset, marketplace|domain|store, country, locale|lang.
Response: { count, total, offset, limit, domain, marketplace, marketplaceSource, locale, currency, catalogMode:"asin"|"search-ideas", items[] }.
**Pass marketplace.** amazon.se ⇒ catalogMode asin (/dp links, SEK). amazon.com ⇒ catalogMode search-ideas (English names, amazon.com search links tagged sw-santawish-20).

### POST /api/v1/products/resolve
Body: { asin|url|keywords, marketplace?, domain?, locale?, preferSearch? }
→ { buyUrl, asin?, linkType, query?, trackingTag, domain, marketplace, marketplaceSource, locale }
**Pass marketplace for the user.** Curated ASINs on amazon.com become English amazon.com search links. Empty body ⇒ default kids gift search (no 400).

### GET /api/v1/health
{ ok, service, storage, redisConfigured, paapi, trackingTag, defaultDomain, marketplaces[{domain,label,tagConfigured}], catalogCount, note, timestamp }

## Buy / inspiration link helpers
- Product: https://www.amazon.se/dp/{ASIN}?tag={tag}
- Kids search: rewrite query + https://www.amazon.se/s?k={keywords}&tag={tag} (amazon.se) or https://www.amazon.com/s?k={keywords}&tag=sw-santawish-20 (amazon.com)
- Tags: amazon.se santawishli03-21 (default) · amazon.com sw-santawish-20
- extractAsinFromUrl supports /dp/, /gp/product/, bare ASINs

## CORS
All /api/v1/* routes: Access-Control-Allow-Origin: *

## UI routes
- / — 3-step create flow + curated starters
- /w/[id] — parent: kid link + Amazon search + buy
- /w/[id]/kid — kid: big “I want…” + suggestions
- /for-agents — copy-paste prompt + curl

## Example curl
curl -sS 'https://santa-wish.vercel.app/api/v1/search?q=lego%20city&ageBand=6-8&interest=toys&limit=5'

curl -sS -X POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill \
  -H 'Content-Type: application/json' \
  -d '{"childName":"Freja","ageBand":"6-8","interests":["toys"],"itemQueries":["LEGO City"]}'

## Constraints
- Max 50 items per wishlist; title max 120 chars
- No paid services required
- Prefer /dp/ ASINs when available; free-text always works as kids search