<!-- 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 -->
# Tomtens önskelista (Santa Wishlist)

> Kids Christmas wishlist builder for agents. Create a wishlist → share shopUrl (or parentUrl + kidUrl) → kid adds wishes → parent shops on amazon.com (US, English search links, tag sw-santawish-20) or amazon.se (Sweden, /dp/ASIN links, tag santawishli03-21). Curated catalog ~600 (amazon.se) / ~560 English (amazon.com).

Base URL: https://santa-wish.vercel.app

## CRITICAL for agents
**Pass `marketplace` for the end user** on search, catalog, resolve and wishlist creation: `marketplace=amazon.com` (US) or `marketplace=amazon.se` (Sweden, default). Without it: `country=US` or `Accept-Language: en-US` ⇒ amazon.com; anything else ⇒ amazon.se. Header alternative: `X-Amazon-Marketplace`. amazon.se returns `/dp/ASIN?tag=santawishli03-21`; amazon.com returns English search links `amazon.com/s?k=…&tag=sw-santawish-20`. Missing q / store never returns 400.

## Quick start
1. GET /api/v1/search?q=lego&ageBand=6-8&interest=toys&limit=5&marketplace=amazon.com&locale=en-US (or marketplace=amazon.se&locale=sv)
2. POST /api/v1/agent/create-and-fill  JSON: {"marketplace":"amazon.com","childName":"Freja","ageBand":"6-8","interests":["toys"],"itemAsins":["B0FPXFQ7MY"],"itemQueries":["LEGO City"],"itemKeywords":["kids football"]}
3. Or POST /api/v1/wishlists then POST .../items with { "name", "asin"?, "url"? }
4. Response includes id, editToken, shopUrl, ownerUrl, parentUrl, kidUrl, marketplace
5. Free-text wishes without ASIN use kids-filtered Amazon search URLs (linkType:"search")
6. Pasted Amazon /dp/… URLs are extracted to ASINs via products/resolve and add-item

## Key links
- [Full agent docs](https://santa-wish.vercel.app/llms-full.txt)
- [OpenAPI](https://santa-wish.vercel.app/openapi.json)
- [For agents UI](https://santa-wish.vercel.app/for-agents)
- [Skill](https://santa-wish.vercel.app/skill.md)
- [Agents guide](https://santa-wish.vercel.app/agents.md)
- [AI plugin](https://santa-wish.vercel.app/.well-known/ai-plugin.json)
- [llms.txt (well-known)](https://santa-wish.vercel.app/.well-known/llms.txt)
- [MCP (Streamable HTTP)](https://santa-wish.vercel.app/api/mcp) — official agent tools; see docs/mcp.md
- [Health](https://santa-wish.vercel.app/api/v1/health) — trackingTag, marketplaces[], catalogCount, paapi
- [Search](https://santa-wish.vercel.app/api/v1/search?q=lego&ageBand=6-8&marketplace=amazon.se&locale=sv)
- [Catalog US](https://santa-wish.vercel.app/api/v1/catalog?limit=24&offset=0&marketplace=amazon.com&locale=en-US) — English, amazon.com links
- [Catalog SE](https://santa-wish.vercel.app/api/v1/catalog?limit=24&offset=0&marketplace=amazon.se&locale=sv) — paginated curated products

## Catalog
- ~600 curated kids Christmas gift ideas (amazon.se ASINs; ~560 in English for amazon.com), imageUrl, ageBands (0-2 / 3-5 / 6-8 / 9-12), categories toys/books/craft/outdoor/sports/tech/games
- GET /api/v1/catalog supports limit (default 48, max 100), offset, marketplace (amazon.com|amazon.se|…), country, locale, q, ageBand, interest(s), ids
- Search remains primary discovery; catalog is starters + examples for agents

## API (CORS *)
- GET /api/v1/search?q=&ageBand=&interest=&limit=&marketplace=&locale=
- POST /api/v1/wishlists
- GET /api/v1/wishlists/:id
- PATCH /api/v1/wishlists/:id (X-Edit-Token)
- POST /api/v1/wishlists/:id/items (X-Edit-Token)
- DELETE /api/v1/wishlists/:id/items/:itemId (X-Edit-Token)
- POST /api/v1/agent/create-and-fill
- POST /api/v1/products/resolve  (body may include marketplace, locale)
- GET /api/v1/catalog?limit=&offset=&marketplace=&locale=
- MCP POST|GET /api/mcp (Streamable HTTP; tools wrap /api/v1/*)
- GET /api/v1/health