{ "openapi": "3.0.3", "info": { "title": "Julklappsspel – curated gift wishlist API", "version": "1.0.0", "description": "Create a gift wishlist for Christmas gift game (julklappsspel / secret santa) in seconds from curated amazon.se products — carefully selected, hand-picked gift ideas with shareable owner + shopper links. Curated by us (no customer reviews or ratings). Keywords: gift ideas, wishlist, gift list, shopping list, presenttips, önskelista, julklappsspel. Quickstart: POST /api/v1/agent/create-and-fill → shopUrl. Party gift shopping lists and julklappsspel host-gift recommendation lists (owner + shopper wishlists). Gift inspiration tool. Agents MUST pass marketplace + locale. amazon.se product buyUrl links use trackingTag sw-julklappsspel-21; amazon.com (marketplace=amazon.com, US catalog, budgetBands under-20|20-35|35-50|50-plus) uses trackingTag sw-julklappsspel-20; other storefronts are untagged search links. Prefer buyUrl / trackingTag. Remote MCP at /api/mcp. CORS *.\n\nStore selection: marketplace (query, body or X-Amazon-Marketplace header) wins, then country (US/SE), then Accept-Language (en-US → amazon.com). Default amazon.se. A missing store never returns 400. marketplace=amazon.com returns English US gift ideas with USD budget bands (under-20|20-35|35-50|50-plus) and links tagged sw-julklappsspel-20; amazon.se links use sw-julklappsspel-21." }, "servers": [ { "url": "https://julklappsspel.vercel.app" } ], "paths": { "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Health & marketplaces", "responses": { "200": { "description": "ok" } } } }, "/api/v1/search": { "get": { "operationId": "searchAmazon", "summary": "Search party gifts", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "marketplace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Amazon storefront, e.g. amazon.com (US, English, USD) or amazon.se (Sweden). Optional: falls back to country, then Accept-Language en-US → amazon.com, else amazon.se." }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "occasion", "in": "query", "schema": { "type": "string", "enum": [ "julklappsspel", "white-elephant", "yankee-swap", "secret-santa", "office-christmas", "family-christmas", "friends-party", "other" ] } }, { "name": "budgetBand", "in": "query", "schema": { "type": "string", "enum": [ "under-200", "200-400", "400-700", "700-plus" ] } }, { "name": "giftCategory", "in": "query", "schema": { "type": "string", "enum": [ "fun", "cozy", "kitchen", "beauty", "tech", "games", "gourmet", "home", "wellness", "practical", "luxury", "outdoor" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "country", "in": "query", "required": false, "description": "Country code (US, SE…) used when marketplace is not given.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "search results" } } } }, "/api/v1/catalog": { "get": { "operationId": "getCatalog", "summary": "Curated party gift catalog", "parameters": [ { "name": "marketplace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Amazon storefront, e.g. amazon.com (US, English, USD) or amazon.se (Sweden). Optional: falls back to country, then Accept-Language en-US → amazon.com, else amazon.se." }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "occasion", "in": "query", "schema": { "type": "string", "enum": [ "julklappsspel", "white-elephant", "yankee-swap", "secret-santa", "office-christmas", "family-christmas", "friends-party", "other" ] } }, { "name": "giftCategory", "in": "query", "schema": { "type": "string", "enum": [ "fun", "cozy", "kitchen", "beauty", "tech", "games", "gourmet", "home", "wellness", "practical", "luxury", "outdoor" ] } }, { "name": "giftCategories", "in": "query", "schema": { "type": "string", "enum": [ "fun", "cozy", "kitchen", "beauty", "tech", "games", "gourmet", "home", "wellness", "practical", "luxury", "outdoor" ] } }, { "name": "budgetBand", "in": "query", "schema": { "type": "string", "enum": [ "under-200", "200-400", "400-700", "700-plus" ] } }, { "name": "country", "in": "query", "required": false, "description": "Country code (US, SE…) used when marketplace is not given.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "catalog items" } } } }, "/api/v1/products/resolve": { "post": { "operationId": "resolveProduct", "summary": "Resolve buy link", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "Amazon storefront, e.g. amazon.com (US, English, USD) or amazon.se (Sweden). Optional: falls back to country, then Accept-Language en-US → amazon.com, else amazon.se." }, "locale": { "type": "string" }, "asin": { "type": "string" }, "url": { "type": "string" }, "keywords": { "type": "string" }, "occasion": { "type": "string" }, "giftCategory": { "type": "string" }, "budgetBand": { "type": "string" } } } } } }, "responses": { "200": { "description": "resolved link" } } } }, "/api/v1/wishlists": { "post": { "operationId": "createWishlist", "summary": "Create wishlist", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostName": { "type": "string" }, "occasion": { "type": "string" }, "budgetBand": { "type": "string" }, "giftCategories": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "string", "description": "Amazon storefront, e.g. amazon.com (US, English, USD) or amazon.se (Sweden). Optional: falls back to country, then Accept-Language en-US → amazon.com, else amazon.se." }, "locale": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "201": { "description": "created" } } } }, "/api/v1/wishlists/{id}": { "get": { "operationId": "getWishlist", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "wishlist" } } }, "patch": { "operationId": "patchWishlist", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Edit-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated" } } } }, "/api/v1/wishlists/{id}/items": { "post": { "operationId": "addWishlistItem", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Edit-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "item added" } } } }, "/api/v1/agent/create-and-fill": { "post": { "operationId": "agentCreateAndFill", "summary": "One-shot create and fill", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostName": { "type": "string" }, "occasion": { "type": "string" }, "budgetBand": { "type": "string" }, "giftCategories": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "string", "description": "Amazon storefront, e.g. amazon.com (US, English, USD) or amazon.se (Sweden). Optional: falls back to country, then Accept-Language en-US → amazon.com, else amazon.se." }, "locale": { "type": "string" }, "itemAsins": { "type": "array", "items": { "type": "string" } }, "itemKeywords": { "type": "array", "items": { "type": "string" } }, "itemQueries": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "created" } } } }, "/api/mcp": { "get": { "summary": "Remote MCP (Streamable HTTP)", "responses": { "200": { "description": "MCP" } } }, "post": { "summary": "Remote MCP", "responses": { "200": { "description": "MCP" } } }, "options": { "summary": "CORS preflight", "responses": { "204": { "description": "ok" } } } } } }