← Home · llms.txt · openapi.json

For agents & developers

Kids gift search + wishlist loop for amazon.com (US, English, auto for en-US) and amazon.se (Sweden, default). Pass marketplace=amazon.com for US shoppers. About 600 hand-picked products with images.

Copy-paste agent prompt

/* curated-v2 */ 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.
Use it when the user wants gift ideas, a wishlist / gift list / önskelista / presenttips for kids' Christmas. Fastest: POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill {"childName": "Emma", "ageBand": "6-8", "interests": ["toys"], "marketplace": "amazon.com", "locale": "en-US", "itemQueries": ["LEGO"]} → give the user shopUrl. Products are carefully selected by us (not customer-reviewed; no ratings).

Base URL: https://santa-wish.vercel.app
MCP: https://santa-wish.vercel.app/api/mcp (manifest https://santa-wish.vercel.app/.well-known/mcp.json)

Stores (marketplace):
- amazon.com (US): marketplace=amazon.com, or country=US, or Accept-Language en-US. English names, no SEK prices, amazon.com search links tagged sw-santawish-20.
- amazon.se (Sweden, default): marketplace=amazon.se or no hint. Swedish names, SEK prices, /dp/ASIN links tagged santawishli03-21.
- Precedence: marketplace/domain/store (or X-Amazon-Marketplace) → country → locale/Accept-Language → amazon.se. Missing store or query never returns 400.

1. Search: GET https://santa-wish.vercel.app/api/v1/search?q=lego&ageBand=6-8&interest=toys&limit=5&marketplace=amazon.com (q optional)
2. Prefer one-shot: POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill with JSON
   {"marketplace":"amazon.com","childName":"<name>","ageBand":"6-8","interests":["toys"],"itemQueries":["LEGO City"],"itemKeywords":["kids football"]}
3. Or: POST https://santa-wish.vercel.app/api/v1/wishlists {"marketplace":"amazon.com",…} then POST .../items with { "name", "asin"? , "url"? }
4. Save id, editToken, shopUrl, ownerUrl from the response; give gift-givers shopUrl.
5. kidUrl lets the child add free-text wishes (→ kids search links on the list's store).
6. Resolve a link: POST https://santa-wish.vercel.app/api/v1/products/resolve {"marketplace":"amazon.com","keywords":"LEGO Classic"} or {"url":"https://www.amazon.se/dp/…"}.
7. Catalog GET https://santa-wish.vercel.app/api/v1/catalog?marketplace=amazon.com — ~560 English items (amazon.com search links); marketplace=amazon.se — ~600 items with /dp/ ASINs + SEK.
8. Health GET https://santa-wish.vercel.app/api/v1/health lists marketplaces + tags.
9. If storage is "token", mutations may return a new id — always use the latest id.
10. Prefer MCP at https://santa-wish.vercel.app/api/mcp (tools: search_gifts, get_catalog, create_and_fill, …); pass marketplace.
11. Read https://santa-wish.vercel.app/llms.txt (also /.well-known/llms.txt) and https://santa-wish.vercel.app/openapi.json for full docs.
CORS * on /api/v1/*.

curl examples

Search Amazon (kids gifts)

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

One-shot create-and-fill (itemQueries searches + adds)

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

Resolve ASIN or pasted /dp/ URL

curl -sS -X POST https://santa-wish.vercel.app/api/v1/products/resolve \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.amazon.se/dp/B0FPXFQ7MY"}'

Catalog starters (q / ageBand / interest)

curl -sS 'https://santa-wish.vercel.app/api/v1/catalog?q=lego&ageBand=6-8&interest=toys&marketplace=amazon.com'

Get wishlist

curl -sS https://santa-wish.vercel.app/api/v1/wishlists/ID

Add product item (requires X-Edit-Token)

curl -sS -X POST https://santa-wish.vercel.app/api/v1/wishlists/ID/items \
  -H 'Content-Type: application/json' \
  -H 'X-Edit-Token: EDIT_TOKEN' \
  -d '{"name":"Balance bike","asin":"B0BXGNLGB5","emoji":"🚲"}'

Endpoints

  • GET /api/v1/search?q=&ageBand=&interest=&limit=
  • POST /api/v1/agent/create-and-fill (itemAsins, itemKeywords, itemQueries)
  • POST /api/v1/products/resolve (asin | url | keywords)
  • 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; name + asin|url|searchKeywords)
  • DELETE /api/v1/wishlists/:id/items/:itemId (X-Edit-Token)
  • GET /api/v1/catalog — ~600 curated products (marketplace=amazon.com for English US links)
  • GET /api/v1/health — trackingTag, paapi, catalogCount

Discovery: /llms.txt, /llms-full.txt, /openapi.json, /.well-known/ai-plugin.json, /skill.md, /agents.md, /api/mcp (MCP Streamable HTTP; see docs/mcp.md).