← Home · llms.txt · openapi.json

For AI agents — gift list quickstart

Build romantic partner gift lists, shopping lists, and wishlists across Amazon storefronts. Always pass marketplace + locale (US: amazon.com / en). ownerUrl = she publishes; shopUrl = he shops. Catalog =100+ real amazon.se /dp ASINs; search on other markets.

Copy-paste agent prompt

You are helping build gift recommendation lists, shopping lists, and wishlists for a girlfriend/wife via the Girlfriend Gifts API.

Base URL: https://girlfriendgifts.vercel.app

ALWAYS pass marketplace + locale matching the end user.
- US example: marketplace=amazon.com&locale=en
- SE example: marketplace=amazon.se&locale=sv
Discover storefronts: GET https://girlfriendgifts.vercel.app/api/v1/marketplaces

1. Search: GET https://girlfriendgifts.vercel.app/api/v1/search?q=pearl%20earrings&marketplace=amazon.com&locale=en&occasion=anniversary&budgetBand=300-700&styleTag=jewelry&limit=5
   - paapi:true → products with /dp/ buyUrl (default storefront when PA-API configured)
   - paapi:false → romantic search deep-links + catalogMatches on the chosen marketplace
2. Prefer one-shot: POST https://girlfriendgifts.vercel.app/api/v1/agent/create-and-fill
   {"recipientName":"Emma","occasion":"anniversary","budgetBand":"300-700","styleTags":["romantic","jewelry"],"relationship":"girlfriend","itemQueries":["gold necklace"],"itemKeywords":["spa gift set"],"marketplace":"amazon.com","locale":"en"}
3. Or POST https://girlfriendgifts.vercel.app/api/v1/wishlists then POST .../items with { "name", "asin"? , "url"? , "marketplace", "locale" }
4. Save id, editToken, ownerUrl, shopUrl.
5. Give her ownerUrl (/w/{{id}}) to publish wishes; give him shopUrl (/w/{{id}}/shop) to buy.
6. Resolve: POST https://girlfriendgifts.vercel.app/api/v1/products/resolve {"asin":"…","marketplace":"amazon.com","locale":"en"} or {"url":"https://www.amazon.com/dp/…","marketplace":"amazon.com","locale":"en"}.
7. Catalog GET https://girlfriendgifts.vercel.app/api/v1/catalog?marketplace=amazon.se&locale=sv — 100+ real amazon.se /dp ASINs for building shopping lists; use search on other markets.
8. Health GET https://girlfriendgifts.vercel.app/api/v1/health.
9. If storage is "token", mutations may return a new id — prefer Upstash Redis for stable share links.
10. Read https://girlfriendgifts.vercel.app/llms.txt and https://girlfriendgifts.vercel.app/openapi.json. MCP (Streamable HTTP): https://girlfriendgifts.vercel.app/api/mcp — also local stdio via npm run mcp (tools require marketplace + locale).
CORS * on /api/v1/*. Tracking: amazon.se product links use ?tag=sw-girlfriend-21 when configured via NEXT_PUBLIC_AMAZON_TAGS_JSON; other storefronts may stay untagged. Prefer buyUrl / trackingTag. Never invent placeholders or reuse santawishli03-21. May earn from qualifying purchases.

curl quickstart

Marketplaces

curl -sS https://girlfriendgifts.vercel.app/api/v1/marketplaces

Search (US)

curl -sS 'https://girlfriendgifts.vercel.app/api/v1/search?q=pearl%20earrings&marketplace=amazon.com&locale=en&occasion=anniversary&budgetBand=300-700&styleTag=jewelry&limit=5'

Create-and-fill

curl -sS -X POST https://girlfriendgifts.vercel.app/api/v1/agent/create-and-fill \
  -H 'Content-Type: application/json' \
  -d '{"recipientName":"Emma","occasion":"anniversary","budgetBand":"300-700","styleTags":["romantic","jewelry"],"relationship":"girlfriend","itemQueries":["gold necklace"],"itemKeywords":["spa gift set"],"marketplace":"amazon.com","locale":"en"}'

Resolve

curl -sS -X POST https://girlfriendgifts.vercel.app/api/v1/products/resolve \
  -H 'Content-Type: application/json' \
  -d '{"keywords":"pearl stud earrings gift for her","marketplace":"amazon.com","locale":"en"}'

Add item

curl -sS -X POST https://girlfriendgifts.vercel.app/api/v1/wishlists/ID/items \
  -H 'Content-Type: application/json' \
  -H 'X-Edit-Token: EDIT_TOKEN' \
  -d '{"name":"Silk sleep mask","searchKeywords":"silk sleep mask","emoji":"😴","marketplace":"amazon.com","locale":"en"}'

Catalog

curl -sS 'https://girlfriendgifts.vercel.app/api/v1/catalog?styleTag=romantic&occasion=valentines&marketplace=amazon.se&locale=sv'

Get wishlist

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

Endpoints

  • GET /api/v1/marketplaces
  • GET /api/v1/search?q=&marketplace=&locale=&occasion=&budgetBand=&styleTag=&limit=
  • POST /api/v1/wishlists → ownerUrl + shopUrl
  • POST /api/v1/agent/create-and-fill
  • GET /api/v1/catalog — 100+ real amazon.se /dp ASINs for list-building
  • GET /api/cron/refresh-catalog — weekly stub

Tags: amazon.se uses ?tag=sw-girlfriend-21 when configured via NEXT_PUBLIC_AMAZON_TAGS_JSON; other storefronts may stay untagged. Still pass marketplace + locale. Never invent placeholders or reuse Santa tags.