{"openapi":"3.1.0","info":{"title":"GiftKai ChatGPT API","description":"External-facing API for GiftKai AI integrations. Allows searching for gifts, browsing trending products, exploring categories, and fetching full product details.","version":"1.0.0"},"servers":[{"url":"https://giftkai.com/_api"}],"paths":{"/gifts/search":{"post":{"summary":"Search for gifts","description":"Core gift search tool. Can use an unstructured natural language query or explicit filters.","operationId":"searchGifts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language description of the gift request (e.g., 'A graduation gift for my daughter who loves gardening')"},"recipient":{"type":"string","description":"Explicit relationship type (e.g., 'mom', 'coworker')"},"occasion":{"type":"string","description":"Explicit occasion type (e.g., 'birthday', 'wedding')"},"budget_min":{"type":"number","description":"Minimum budget in USD"},"budget_max":{"type":"number","description":"Maximum budget in USD"},"interests":{"type":"array","items":{"type":"string"},"description":"Array of interests (e.g., ['coffee', 'hiking'])"},"vibes":{"type":"array","items":{"type":"string"},"description":"Array of personality traits or vibes (e.g., ['cozy', 'practical'])"},"limit":{"type":"number","description":"Number of results to return (max 24)","default":12}}}}}},"responses":{"200":{"description":"A list of gift recommendations","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"recommendations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"price":{"type":"number","nullable":true},"retailer":{"type":"string"},"image_url":{"type":"string"},"product_url":{"type":"string"},"affiliate_url":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"match_score":{"type":"number"}}}},"parsed_intent":{"type":"object","properties":{"recipient":{"type":"string","nullable":true},"occasion":{"type":"string","nullable":true},"budget_min":{"type":"number"},"budget_max":{"type":"number"},"interests":{"type":"array","items":{"type":"string"}},"vibes":{"type":"array","items":{"type":"string"}}}},"total_results":{"type":"number"}}}}}}}}},"/gifts/trending":{"get":{"summary":"Get trending gift products","description":"Returns the most trending gift products over the last 30 days, ranked by upvotes and recommendation count.","operationId":"getTrendingGifts","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of trending products to return (default 24)","schema":{"type":"number","default":24}}],"responses":{"200":{"description":"A list of trending gift products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"price":{"type":"number","nullable":true},"image_url":{"type":"string"},"product_url":{"type":"string"},"affiliate_url":{"type":"string"},"retailer":{"type":"string"},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}},"trending_score":{"type":"number"}}}}}}}}}}}},"/gifts/categories":{"get":{"summary":"Get all gift categories","description":"Returns all available gift tags/categories in the system, along with how many requests are tagged with each.","operationId":"getGiftCategories","parameters":[],"responses":{"200":{"description":"A list of gift categories","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"tag_type":{"type":"string"},"request_count":{"type":"number"}}}}}}}}}}}},"/gifts/product":{"get":{"summary":"Get product detail","description":"Fetch complete details of a specific product by its numeric ID. Pass the product ID as the `id` query parameter (e.g. `?id=1234`).","operationId":"getProductDetail","parameters":[{"name":"id","in":"query","required":true,"description":"The numeric product ID to fetch details for","schema":{"type":"number"}}],"responses":{"200":{"description":"Full product details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"price":{"type":"number","nullable":true},"compare_at_price":{"type":"number","nullable":true},"retailer":{"type":"string"},"brand_name":{"type":"string"},"image_url":{"type":"string"},"product_url":{"type":"string"},"affiliate_url":{"type":"string"},"category":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}},"domain":{"type":"string"}}}}}},"404":{"description":"Product not found"}}}},"/feeds/products":{"get":{"summary":"Get products feed","description":"Bulk JSON feed of platform products with categorized tags. Intended for AI embeddings, LLM context, or catalog synchronization. Supports cursor-based pagination via `limit` and `offset`.","operationId":"getFeedsProducts","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of products to return per page (max 500, default 100)","schema":{"type":"number","default":100,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Number of products to skip for pagination (default 0)","schema":{"type":"number","default":0}}],"responses":{"200":{"description":"A paginated list of products with enriched metadata","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number","nullable":true},"image":{"type":"string"},"product_url":{"type":"string"},"merchant":{"type":"string"},"recipient_tags":{"type":"array","items":{"type":"string"}},"occasion_tags":{"type":"array","items":{"type":"string"}},"budget_band":{"type":"string","nullable":true,"description":"Budget band: under_25, 25_50, 50_100, 100_250, 250_plus"},"personality_tags":{"type":"array","items":{"type":"string"}},"why_this_gift":{"type":"string","nullable":true},"avoid_if":{"type":"string","nullable":true}}}},"total_count":{"type":"number","description":"Total number of products in the catalog"},"limit":{"type":"number"},"offset":{"type":"number"}}}}}}}}}}}