{ "openapi": "3.1.0", "info": { "title": "Baby Registry – curated gift wishlist API", "version": "1.4.0", "description": "Create a gift wishlist for baby registry / baby shower 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, babyshower och bebispresenter. Quickstart: POST /api/v1/agent/create-and-fill → shopUrl. Baby Registry gift inspiration API. Prefer buyUrl + trackingTag in responses; buyUrl/trackingTag preferred; legacy Url/Tag fields are compat aliases. Agent-first age-stage baby registry. MULTI-MARKETPLACE: agents MUST pass marketplace + locale on search/catalog/resolve. Open Amazon search for baby essentials (PA-API when configured, else search deep-links). REAL /dp/{ASIN} when ASIN trusted for storefront (amazon.se curated); else search deep-links. amazon.se uses tracking tag sw-babyreg-21 (tagConfigured:true). Other storefronts untagged until per-domain IDs exist. Never invent placeholder tags or reuse santawishli03-21 / girlfriendgift-21. Age stages expecting|0-3m|3-6m|6-12m|12-24m|toddler. Categories sleep/feeding/diapering/gear/clothing/safety/play/bath. API returns ownerUrl + shopUrl. CORS * on /api/v1/*.", "contact": { "name": "maggat", "url": "https://babyregistry.vercel.app" } }, "servers": [ { "url": "https://babyregistry.vercel.app" }, { "url": "http://localhost:3000" } ], "tags": [ { "name": "search" }, { "name": "wishlists" }, { "name": "catalog" }, { "name": "agent" }, { "name": "meta" } ], "paths": { "/api/v1/health": { "get": { "tags": [ "meta" ], "summary": "Health check", "operationId": "getHealth", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/api/v1/catalog": { "get": { "tags": [ "catalog" ], "summary": "Gift catalog with REAL /dp/ buy URLs when ASIN present", "operationId": "getCatalog", "parameters": [ { "name": "q", "in": "query", "description": "Full-text search", "schema": { "type": "string" } }, { "name": "ageBand", "in": "query", "schema": { "$ref": "#/components/schemas/AgeBand" } }, { "name": "interest", "in": "query", "description": "Single interest filter", "schema": { "type": "string" } }, { "name": "interests", "in": "query", "description": "Comma-separated interests", "schema": { "type": "string" } }, { "name": "marketplace", "in": "query", "required": true, "description": "Amazon storefront domain or id (e.g. amazon.com, amazon.se, us, se). Required for correct buy deep-links.", "schema": { "type": "string", "example": "amazon.se" } }, { "name": "locale", "in": "query", "required": true, "description": "BCP-47-ish locale for search cues (en, sv, de, fr, es).", "schema": { "type": "string", "example": "sv" } }, { "name": "domain", "in": "query", "required": false, "description": "Alias for marketplace", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" } } } } } } }, "/api/v1/products/resolve": { "post": { "tags": [ "catalog" ], "summary": "Resolve ASIN, pasted amazon.se URL, or keywords to buy link", "operationId": "resolveProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asin": { "type": "string", "description": "10-char Amazon ASIN" }, "keywords": { "type": "string" }, "marketplace": { "type": "string", "description": "Amazon storefront (required)", "example": "amazon.com" }, "domain": { "type": "string", "description": "Alias for marketplace" }, "locale": { "type": "string", "description": "Locale for search cues (required)", "example": "en" }, "url": { "type": "string", "description": "Pasted Amazon product URL" } }, "required": [ "locale", "marketplace" ] } } } }, "responses": { "200": { "description": "Resolved link", "content": { "application/json": { "schema": { "type": "object", "properties": { "buyUrl": { "type": "string", "format": "uri", "description": "Curated Amazon buy URL (preferred). Same value as legacy Url field." }, "affiliateUrl": { "type": "string", "format": "uri", "description": " Compat alias for buyUrl." }, "asin": { "type": "string" }, "linkType": { "$ref": "#/components/schemas/LinkType" }, "trackingTag": { "type": "string", "nullable": true, "description": "Associates tracking tag when configured (preferred). Null in search-mode." }, "affiliateTag": { "type": "string", "description": " Compat alias for trackingTag." }, "domain": { "type": "string" }, "catalogCount": { "type": "integer", "description": "Curated catalog size (100+ baby registry essentials)" }, "paapi": { "type": "boolean" } }, "required": [ "buyUrl", "linkType", "affiliateUrl" ] } } } } }, "description": "Accepts asin, url (amazon.se/dp/…), and/or keywords." } }, "/api/v1/agent/create-and-fill": { "post": { "tags": [ "agent" ], "summary": "One-shot create wishlist and add ASINs/keywords", "operationId": "agentCreateAndFill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateAndFillBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistCreateResponse" } } } } } } }, "/api/v1/wishlists": { "post": { "tags": [ "wishlists" ], "summary": "Create wishlist", "operationId": "createWishlist", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWishlistBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistCreateResponse" } } } } } } }, "/api/v1/wishlists/{id}": { "get": { "tags": [ "wishlists" ], "summary": "Get wishlist", "operationId": "getWishlist", "parameters": [ { "$ref": "#/components/parameters/WishlistId" } ], "responses": { "200": { "description": "Wishlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistGetResponse" } } } }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "wishlists" ], "summary": "Update wishlist metadata or replace items", "operationId": "patchWishlist", "parameters": [ { "$ref": "#/components/parameters/WishlistId" }, { "$ref": "#/components/parameters/EditToken" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWishlistBody" } } } }, "responses": { "200": { "description": "Updated (token mode may return new id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistMutateResponse" } } } }, "401": { "description": "Missing edit token" }, "404": { "description": "Not found or bad token" } } } }, "/api/v1/wishlists/{id}/items": { "post": { "tags": [ "wishlists" ], "summary": "Add wish item (asin → /dp/ product link)", "operationId": "addWishlistItem", "parameters": [ { "$ref": "#/components/parameters/WishlistId" }, { "$ref": "#/components/parameters/EditToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddItemBody" } } } }, "responses": { "201": { "description": "Item added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistMutateResponse" } } } } }, "description": "Accept name/title, asin, url (pasted /dp link), searchKeywords, or catalogId." } }, "/api/v1/wishlists/{id}/items/{itemId}": { "delete": { "tags": [ "wishlists" ], "summary": "Delete wish item", "operationId": "deleteWishlistItem", "parameters": [ { "$ref": "#/components/parameters/WishlistId" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/EditToken" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WishlistMutateResponse" } } } } } } }, "/api/v1/search": { "get": { "tags": [ "search" ], "summary": "Open Amazon.se kids gift search", "description": "If PA-API keys are set, returns real products. Otherwise ranked kids-filtered Amazon.se search deep-link cards plus matching curated catalog ASINs.", "operationId": "searchAmazon", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "ageBand", "in": "query", "schema": { "$ref": "#/components/schemas/AgeBand" } }, { "name": "interest", "in": "query", "schema": { "type": "string" }, "description": "Category/interest filter" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, { "name": "marketplace", "in": "query", "required": true, "description": "Amazon storefront domain or id (e.g. amazon.com, amazon.se, us, se). Required for correct buy deep-links.", "schema": { "type": "string", "example": "amazon.se" } }, { "name": "locale", "in": "query", "required": true, "description": "BCP-47-ish locale for search cues (en, sv, de, fr, es).", "schema": { "type": "string", "example": "sv" } }, { "name": "domain", "in": "query", "required": false, "description": "Alias for marketplace", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Missing q" } } } } }, "components": { "parameters": { "WishlistId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Short Redis id or t.* token id" }, "EditToken": { "name": "X-Edit-Token", "in": "header", "required": true, "schema": { "type": "string" } } }, "schemas": { "AgeBand": { "type": "string", "enum": [ "expecting", "0-3m", "3-6m", "6-12m", "12-24m", "toddler" ] }, "Interest": { "type": "string", "enum": [ "sleep", "feeding", "diapering", "gear", "clothing", "safety", "play", "bath" ] }, "LinkType": { "type": "string", "enum": [ "product", "search" ] }, "WishlistItem": { "type": "object", "required": [ "id", "title", "createdAt" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "catalogId": { "type": "string" }, "asin": { "type": "string", "nullable": true }, "searchKeywords": { "type": "string" }, "emoji": { "type": "string" }, "buyUrl": { "type": "string", "format": "uri", "description": "Curated Amazon buy URL (preferred). Same value as legacy Url field." }, "affiliateUrl": { "type": "string", "format": "uri", "description": " Compat alias for buyUrl." }, "linkType": { "$ref": "#/components/schemas/LinkType" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Wishlist": { "type": "object", "required": [ "id", "childName", "items", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "childName": { "type": "string" }, "ageBand": { "$ref": "#/components/schemas/AgeBand" }, "interests": { "type": "array", "items": { "$ref": "#/components/schemas/Interest" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WishlistItem" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateWishlistBody": { "type": "object", "properties": { "childName": { "type": "string" }, "ageBand": { "$ref": "#/components/schemas/AgeBand" }, "interests": { "type": "array", "items": { "$ref": "#/components/schemas/Interest" } }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "catalogId": { "type": "string" }, "asin": { "type": "string" }, "searchKeywords": { "type": "string" }, "emoji": { "type": "string" } } } }, "marketplace": { "type": "string" }, "locale": { "type": "string" } } }, "AgentCreateAndFillBody": { "type": "object", "properties": { "childName": { "type": "string" }, "ageBand": { "$ref": "#/components/schemas/AgeBand" }, "interests": { "type": "array", "items": { "$ref": "#/components/schemas/Interest" } }, "itemAsins": { "type": "array", "items": { "type": "string" }, "description": "Amazon ASINs → /dp/ links" }, "itemKeywords": { "type": "array", "items": { "type": "string" }, "description": "Free-text → search links" }, "itemQueries": { "type": "array", "items": { "type": "string" }, "description": "Free-text queries searched via PA-API or kids search links and added" }, "marketplace": { "type": "string", "example": "amazon.se" }, "locale": { "type": "string", "example": "sv" } }, "required": [ "locale", "marketplace" ] }, "PatchWishlistBody": { "type": "object", "properties": { "childName": { "type": "string" }, "ageBand": { "oneOf": [ { "$ref": "#/components/schemas/AgeBand" }, { "type": "null" } ] }, "interests": { "type": "array", "items": { "$ref": "#/components/schemas/Interest" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WishlistItem" } } } }, "AddItemBody": { "type": "object", "properties": { "title": { "type": "string" }, "name": { "type": "string", "description": "Alias for title" }, "notes": { "type": "string" }, "catalogId": { "type": "string" }, "asin": { "type": "string", "description": "When set, buyUrl is /dp/ASIN?tag=" }, "searchKeywords": { "type": "string" }, "emoji": { "type": "string" }, "url": { "type": "string", "description": "Pasted amazon.se/dp URL — ASIN extracted when possible" } } }, "WishlistCreateResponse": { "type": "object", "required": [ "id", "editToken", "ownerUrl", "shopUrl", "wishlist", "storage" ], "properties": { "id": { "type": "string" }, "editToken": { "type": "string" }, "ownerUrl": { "type": "string", "format": "uri" }, "shopUrl": { "type": "string", "format": "uri" }, "wishlist": { "$ref": "#/components/schemas/Wishlist" }, "storage": { "type": "string", "enum": [ "redis", "token" ] } } }, "WishlistGetResponse": { "type": "object", "required": [ "id", "wishlist", "ownerUrl", "shopUrl", "storage" ], "properties": { "id": { "type": "string" }, "wishlist": { "$ref": "#/components/schemas/Wishlist" }, "ownerUrl": { "type": "string", "format": "uri" }, "shopUrl": { "type": "string", "format": "uri" }, "storage": { "type": "string", "enum": [ "redis", "token" ] } } }, "WishlistMutateResponse": { "allOf": [ { "$ref": "#/components/schemas/WishlistCreateResponse" }, { "type": "object", "properties": { "previousId": { "type": "string" }, "item": { "$ref": "#/components/schemas/WishlistItem" } } } ] }, "CatalogResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "trackingTag": { "type": "string", "nullable": true, "description": "Associates tracking tag when configured (preferred). Null in search-mode." }, "affiliateTag": { "type": "string", "description": " Compat alias for trackingTag." }, "domain": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "asin": { "type": "string", "nullable": true }, "name": { "type": "string" }, "blurb": { "type": "string" }, "priceSek": { "type": "number" }, "category": { "type": "string" }, "emoji": { "type": "string" }, "ageBands": { "type": "array", "items": { "type": "string" } }, "interests": { "type": "array", "items": { "type": "string" } }, "searchKeywords": { "type": "string" }, "affiliateUrl": { "type": "string", "format": "uri" }, "linkType": { "$ref": "#/components/schemas/LinkType" } } } }, "catalogCount": { "type": "integer", "description": "Curated catalog size (100+ baby registry essentials)" }, "paapi": { "type": "boolean" } } }, "Health": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "storage": { "type": "string" }, "redisConfigured": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "paapi": { "type": "boolean" }, "trackingTag": { "type": "string", "nullable": true, "description": "Associates tracking tag when configured (preferred). Null in search-mode." }, "affiliateTag": { "type": "string", "description": " Compat alias for trackingTag." }, "domain": { "type": "string" }, "catalogCount": { "type": "integer", "description": "Curated catalog size (100+ baby registry essentials)" } } }, "SearchResponse": { "type": "object", "properties": { "q": { "type": "string" }, "query": { "type": "string", "description": "Kids-rewritten query" }, "paapi": { "type": "boolean" }, "hint": { "type": "string" }, "count": { "type": "integer" }, "trackingTag": { "type": "string", "nullable": true, "description": "Associates tracking tag when configured (preferred). Null in search-mode." }, "affiliateTag": { "type": "string", "description": " Compat alias for trackingTag." }, "domain": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "catalogMatches": { "type": "array", "items": { "type": "object" } }, "catalogCount": { "type": "integer", "description": "Curated catalog size (100+ baby registry essentials)" } } }, "SearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "asin": { "type": "string" }, "imageUrl": { "type": "string" }, "price": { "type": "string" }, "buyUrl": { "type": "string", "format": "uri", "description": "Curated Amazon buy URL (preferred). Same value as legacy Url field." }, "affiliateUrl": { "type": "string", "description": " Compat alias for buyUrl." }, "linkType": { "type": "string", "enum": [ "product", "search" ] }, "query": { "type": "string" }, "blurb": { "type": "string" }, "emoji": { "type": "string" } } }, "Product": { "type": "object", "required": [ "asin", "title", "buyUrl", "linkType", "affiliateUrl" ], "properties": { "asin": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "type": "string" }, "price": { "type": "string" }, "detailPageUrl": { "type": "string" }, "buyUrl": { "type": "string", "format": "uri", "description": "Curated Amazon buy URL (preferred). Same value as legacy Url field." }, "affiliateUrl": { "type": "string", "description": " Compat alias for buyUrl." }, "linkType": { "type": "string", "enum": [ "product" ] } } } } } }