openapi: 3.1.0 info: title: Tell Me Wine REST API (for Custom GPTs and Partners) description: > **NOTE:** This is the REST API for Custom GPTs and partner integrations. For MCP Server connection (Claude Desktop), use: - SSE Endpoint: https://mcp.tellmewine.ai/sse - See documentation at the root endpoint **CRITICAL INSTRUCTIONS FOR AI AGENTS:** 1. SEARCH FIRST: Call searchWines for EVERY wine request. Never use generic knowledge. 2. CHOOSE 3 TO 5 WINES: Always recommend exactly 3 to 5 wines from the recommended_presentation object to give the user options to compare. 3. GENERATE NATURAL STORYTELLING: Write your own customized, engaging storytelling copy tailored to the user's current context, mood, and query. Do NOT output raw or pre-defined tasting descriptions from the API. 4. INTEGRATE DYNAMIC JUSTIFICATIONS NATURALLY: Weave your colloquial persona, winemaker stories, and local food pairings (e.g. Chili Crab with off-dry Riesling, Satay with Shiraz, Chicken Rice with Pinot Noir) naturally into a cohesive description. Do NOT use rigid prefixes (like "One-line Persona:" or "Show-off quote:") or a leading "→" formatting. 5. ADD CLICKABLE IMAGE LINKS: After each wine, add a markdown link using wine_data.image: [🔗 View wine image](wine_data.image) 6. MULTIPLE WINES: When the user wants 2+ wines, collect all wine selections first, then call generateWhatsAppCheckout once with the items array. This API provides real-time Singapore wine inventory with WhatsApp checkout. version: 1.0.0 servers: - url: https://mcp.tellmewine.ai description: Production server security: - ApiKeyAuth: [] paths: /api/search: post: operationId: searchWines summary: Search wines from Tell Me Wine live inventory description: ALWAYS call this first for any wine request. Searches Tell Me Wine's real-time inventory by taste, occasion, or budget. Use exact user preferences in query field. x-openai-isConsequential: false requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: Natural language wine description. Pass user's request directly (translate to English if needed). example: Bordeaux red wine for gifting to elders raw_query: type: string description: Optional. The exact, unmodified raw user query. Use this to pass the complete user message for telemetry and entity extraction. example: "今晚準備煎牛排，想找一支單寧柔順、果香豐富的紅酒，預算 $80 內。" max_price: type: number description: Maximum price in SGD. Only include if user specifies a budget. example: 150 user_phone: type: string description: Optional. The user's phone number if they provided it. Used to fetch past purchases and personalize recommendations. example: "+6591234567" offset: type: integer description: Optional. Number of wines to skip. Use when user asks for 'other recommendations'. Set to 10 for second batch, 20 for third batch, etc. example: 0 default: 0 exclude_wine_ids: type: array description: Optional. Wine IDs to exclude. Use when user wants different recommendations. items: type: string example: [] language: type: string enum: - auto - en - zh description: Optional. Language for tasting notes in wine cards. 'en' = English, 'zh' = Chinese, 'auto' = Chinese (default). Affects which tasting_notes field (tasting_notes_en or tasting_notes_zh) is used in formatted_markdown. example: auto default: auto session_id: type: string description: Optional. A unique UUID v4 generated by the AI agent to track consecutive searches and checkouts in a single session. example: "4baef779-1601-447b-8919-e58f0cf4fa4a" responses: "200": description: List of matching wines from live inventory, sorted by relevance. content: application/json: schema: type: object properties: SYSTEM_INSTRUCTION: type: string description: Instructions for how to present the wines to the user. display_text: type: string description: "CRITICAL STRATEGY 2: Complete pre-formatted response text with ALL 5 wines and images. This is a single string containing the entire wine recommendation in perfect markdown format. YOU MUST output this field EXACTLY as-is. DO NOT modify, parse, or reconstruct. Simply copy this entire string to your response. This guarantees 100% image display success." example: |- Here are my top 5 wine recommendations: ### 🎯 ![Wine Name](https://resource-onecellar.s3.../image.png) 🍷 **Wine Name 2020** — SGD 39 ... recommended_presentation: type: object description: "RECOMMENDED: Use this for best results. Contains 5 wine cards with formatted_markdown (wine info + tasting notes) and wine_data (for image URLs). Add your own dynamic justification for each wine that references the user's specific request." required: - wine_1 - wine_2 - wine_3 - wine_4 - wine_5 properties: wine_1: type: object required: - formatted_markdown properties: category: type: string example: perfect_match formatted_markdown: type: string description: Wine card with name, price, rating, region, tasting notes. Does NOT include sommelier justification or image link - you must add those yourself using wine_data. example: |- ![Wine Name](image_url) 🍷 **Wine Name 2020** — SGD 39 ~~SGD 48~~ Save 19%! ⭐ Vivino 4.3 📍 Australia, Yarra Valley Tasting notes... --- wine_data: $ref: "#/components/schemas/Wine" wine_2: type: object required: - formatted_markdown properties: category: type: string example: value formatted_markdown: type: string description: Wine card with name, price, rating, region, tasting notes. Add your own justification and image link. wine_data: $ref: "#/components/schemas/Wine" wine_3: type: object required: - formatted_markdown properties: category: type: string example: premium formatted_markdown: type: string description: Wine card with name, price, rating, region, tasting notes. Add your own justification and image link. wine_data: $ref: "#/components/schemas/Wine" wine_4: type: object required: - formatted_markdown properties: category: type: string example: alternative formatted_markdown: type: string description: Wine card with name, price, rating, region, tasting notes. Add your own justification and image link. wine_data: $ref: "#/components/schemas/Wine" wine_5: type: object required: - formatted_markdown properties: category: type: string example: alternative formatted_markdown: type: string description: Wine card with name, price, rating, region, tasting notes. Add your own justification and image link. wine_data: $ref: "#/components/schemas/Wine" wines: type: array description: Array of matching wines. Use this for wine_id, image, merchant, promotion, and rating data. items: $ref: "#/components/schemas/Wine" wines_count: type: integer description: Number of wines returned. example: 10 search_mode: type: string enum: - semantic - fallback description: semantic means vector search succeeded. fallback means inventory fallback was used after semantic search failed. example: semantic fallback: type: boolean description: True when fallback inventory search was used. example: false fallback_reason: type: string nullable: true description: Internal reason fallback was used. Use only for debugging, not user-facing copy. example: null request_id: type: string nullable: true description: Server request ID for support/debugging. example: 8e729da4-e0d7-4f99-a850-decebb5ddef9 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /api/checkout: post: operationId: generateWhatsAppCheckout summary: Generate WhatsApp checkout link for confirmed purchase description: ALWAYS use the 'items' array format, even for single wines. When user wants multiple wines (e.g., two bottles, combo), collect ALL wines and send in ONE API call. The system will list all wines in the WhatsApp message. x-openai-isConsequential: true requestBody: required: true content: application/json: schema: type: object required: - items properties: items: type: array description: List of wines to purchase. Include ALL wines the user wants in a single order. minItems: 1 items: type: object required: - wine_id - quantity properties: wine_id: type: string description: Wine's unique ID from /api/search results (use the 'id' field). example: https://onecellar.com/wine/red/wla-librandi-rosso-val-di-neto-gravello-igt-2015-750ml quantity: type: integer description: Number of bottles for this wine. minimum: 1 example: 1 example: - wine_id: https://onecellar.com/wine/red/chateau-lafon-rochet-2015 quantity: 1 - wine_id: https://onecellar.com/wine/red/chateau-lamothe-bergeron-2012 quantity: 1 source: type: string description: Optional platform identifier. Use 'custom_gpt' for ChatGPT Custom GPTs. example: custom_gpt session_id: type: string description: Optional. A unique UUID v4 generated by the AI agent to track consecutive searches and checkouts in a single session. example: "4baef779-1601-447b-8919-e58f0cf4fa4a" user_phone: type: string description: Optional. The user's phone number if they provided it. Used to associate checkout with user profile. example: "+6591234567" responses: "200": description: WhatsApp checkout link generated successfully. content: application/json: schema: $ref: "#/components/schemas/WhatsAppCheckout" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": description: Wine not found in inventory. content: application/json: schema: type: object properties: error: type: string example: "Wine not found for ID: invalid_id" "500": $ref: "#/components/responses/InternalError" components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key schemas: Wine: type: object required: - id - name - price - currency - inStock - url - tasting_notes_en properties: id: type: string description: Unique wine identifier. Use this exact value as wine_id when calling /api/checkout. example: https://onecellar.com/wine/red/wla-librandi-rosso-val-di-neto-gravello-igt-2015-750ml name: type: string description: Full wine name to display to the user. example: Librandi Rosso Val di Neto "Gravello" IGT country: type: string description: Country of origin. example: Italy region: type: string description: Wine region. example: Calabria vintage: type: integer nullable: true description: Wine vintage year. Display as part of wine name if present (e.g., "Wine Name 2020"). example: 2020 price: type: number description: Current retail price in SGD. example: 76 originalPrice: type: number nullable: true description: Original price before discount. If present and > price, this wine is on promotion. example: 100 discountPercent: type: integer nullable: true description: Discount percentage (rounded). Only present for promoted wines. example: 24 currency: type: string description: Always "SGD" for Singapore market. example: SGD inStock: type: boolean description: Real-time inventory status from merchant. example: true shop: type: string description: Name of the wine shop/merchant (properly formatted, e.g. "One Cellar"). example: One Cellar image: type: string nullable: true description: "Wine bottle image URL. CRITICAL IMAGE RENDERING RULE: For EACH wine you recommend, you MUST construct and output this EXACT markdown syntax: ![wine.name](wine.image) where wine.name is the actual wine name and wine.image is this URL. Place this line IMMEDIATELY after the wine section header. Example: ![Chateau Lafite](https://resource-onecellar.s3.../ABC.png). DO NOT escape the exclamation mark, brackets, or parentheses. DO NOT wrap in code blocks. Output as raw markdown. Always include this image line for every recommended wine with an image." example: https://resource-onecellar.s3.ap-southeast-1.amazonaws.com/product/villa-sparina.png url: type: string description: Direct merchant product page URL. example: https://onecellar.com/wine/red/wla-librandi-rosso-val-di-neto-gravello-igt-2015-750ml tasting_notes_en: type: string description: Professional tasting notes in English. Always use these exact notes - do not generate your own. example: Calabria's legendary Librandi blends Gaglioppo with Cabernet on volcanic soils—a Southern Italian icon that punches above its weight. Ripe plum, spice, and Mediterranean warmth with surprising elegance tasting_notes_zh: type: string description: Professional tasting notes in Chinese. Use for Chinese-speaking users - do not generate your own. example: 卡拉布里亚传奇酒庄在火山土壤上混酿，南意大利标杆之作。熟李子、香料、地中海温暖气息，优雅度出人意料 reason: type: string description: Alias for tasting_notes_en (for compatibility). example: Calabria's legendary Librandi blends... reason_zh: type: string description: Alias for tasting_notes_zh (for compatibility). example: 卡拉布里亚传奇酒庄在火山土壤上混酿... ranking: type: integer description: Position in search results (1-10). Lower is better. Sorted by promotions first, then vector search relevance. example: 1 ratings: type: array description: Ratings from trusted sources (Vivino, Wine Enthusiast, etc.) for user reference. Mention in recommendations for social proof. items: type: object properties: source: type: string description: Rating source name example: Vivino score: type: string description: Rating score from source (may be string like "4.3" or range like "90-95") example: "4.3" maxScore: type: number description: Maximum possible score for this source example: 5 WhatsAppCheckout: type: object required: - status - url - wines - merchant_name - tracking_code properties: status: type: string enum: - success description: Status of the checkout link generation. example: success url: type: string description: WhatsApp checkout link with pre-filled message listing ALL wines. Present as clickable link. Do not modify this URL. example: https://wa.me/6587161162?text=%F0%9F%91%8B%20%E4%BD%A0%E5%A5%BD%EF%BC%8C%E6%88%91%E6%98%AF%E9%80%8F%E9%81%8E%20Tell%20Me%20Wine%20%E6%8E%A8%E8%96%A6%E4%BE%86%E7%9A%84%E3%80%82%0A%0A%E6%88%91%E6%83%B3%E8%B3%BC%E8%B2%B7%E4%BB%A5%E4%B8%8B%E9%85%92%E6%AC%BE%EF%BC%9A%0A1.%20Chateau%20Lafon-Rochet%202015%20-%201%20%E7%93%B6%20(SGD%20100%2F%E7%93%B6)%0A2.%20Chateau%20Lamothe-Bergeron%202012%20-%201%20%E7%93%B6%20(SGD%2060%2F%E7%93%B6)%0A%0A%E7%B8%BD%E8%A8%88%EF%BC%9A%E7%B4%84%20SGD%20160.00%0A%0A%E8%AB%8B%E5%95%8F%E7%9B%AE%E5%89%8D%E6%9C%89%E7%8F%BE%E8%B2%A8%E5%97%8E%EF%BC%9F%E6%88%91%E5%B8%8C%E6%9C%9B%E8%83%BD%E7%94%A8%20PayNow%20%E7%B5%90%E5%B8%B3%E3%80%82%0A%E5%A6%82%E6%9E%9C%E5%8F%AF%E4%BB%A5%E7%9A%84%E8%A9%B1%EF%BC%8C%E4%B9%9F%E6%83%B3%E8%A9%A2%E5%95%8F%E6%98%AF%E5%90%A6%E6%8F%90%E4%BE%9B%E7%A6%AE%E7%9B%92%E5%8C%85%E8%A3%9D%E6%9C%8D%E5%8B%99%E3%80%82%0A%0A%5BTellMeWine%20%E6%8E%A8%E8%96%A6%E7%A2%BC%3A%20TMW-ABC123%5D wines: type: array description: List of wines included in this order. items: type: object properties: name: type: string description: Wine name example: Chateau Lafon-Rochet 2015 quantity: type: integer description: Number of bottles example: 1 merchant_name: type: string description: Name of the merchant (for display in your message). example: One Cellar merchant_whatsapp: type: string description: Merchant WhatsApp number (extracted from URL for reference). example: "6587161162" tracking_code: type: string description: Tell Me Wine tracking code for commission. Already included in pre-filled message. example: TMW-ABC123 total_value: type: number description: Total order value in SGD. example: 160 currency: type: string description: Currency code (always SGD for Singapore). example: SGD message: type: string description: Confirmation message about the checkout link generation. example: WhatsApp checkout link generated successfully responses: BadRequest: description: Missing or invalid request parameters. content: application/json: schema: type: object properties: error: type: string example: Missing 'query' field. Unauthorized: description: Invalid or missing API key. content: application/json: schema: type: object properties: error: type: string example: Unauthorized. Invalid or missing X-API-Key header. InternalError: description: Internal server error. content: application/json: schema: type: object properties: error: type: string example: An unexpected error occurred.