{"openapi":"3.0.3","info":{"title":"Netcore Unbxd Shopping Assistant API","version":"1.2.0","description":"OpenAPI specification generated from the Netcore Unbxd Shopping Assistant API Integration Guide (Version 1.2, October 2026). Confirm endpoint behavior and schemas against the deployed API before production use."},"servers":[{"url":"https://gus.assistant.unbxd.io","description":"United States (preferred for US sites)"},{"url":"https://aus.assistant.unbxd.io","description":"United States (alternate; use if advised by Netcore Unbxd)"},{"url":"https://auk.assistant.unbxd.io","description":"United Kingdom"},{"url":"https://aapac.assistant.unbxd.io","description":"Asia Pacific (APAC)"},{"url":"https://ganz.assistant.unbxd.io","description":"Australia & New Zealand (ANZ)"}],"tags":[{"name":"Conversations","description":"Create conversations, send messages, and retrieve conversation history."},{"name":"Conversation Starters","description":"Retrieve suggested questions and optional welcome messages."}],"security":[{"ShoppingAssistantToken":[]}],"paths":{"/v1/sites/{sitekey}/conversation":{"post":{"tags":["Conversations"],"operationId":"startConversation","summary":"Start Conversation","description":"Creates a new conversation for a shopper and returns its ID. Call this for the first message or when the shopper starts a new chat.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/Uid"}],"responses":{"200":{"description":"Conversation created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartConversationResponse"},"example":{"conversation_id":"6f1c2a8e-3b7d-4f0a-9c55-1e2d3f4a5b6c"}},"text/plain":{"schema":{"type":"string"},"example":"No soup for you!"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}},"/v1/sites/{sitekey}/conversation/{conversationid}/chat":{"post":{"tags":["Conversations"],"operationId":"sendMessage","summary":"Send Message","description":"Sends a shopper message and returns the complete assistant reply. The message field is limited to 1,000 characters. The API may take several seconds to respond.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/ConversationId"},{"$ref":"#/components/parameters/Uid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"message":"Show me waterproof ones in black"}}}},"responses":{"200":{"description":"Assistant reply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"message":"Here are black waterproof running shoes from Nike.","products":[{"uniqueId":"SKU-2040","title":"Pegasus Trail GTX","price":99,"imageUrl":"https://cdn.example.com/sku-2040.jpg","productUrl":"https://www.example.com/p/sku-2040"}],"filters":[{"field":"size","options":["8","9","10","11"]}]}},"text/plain":{"schema":{"type":"string"},"example":"No soup for you!"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}},"/v1/sites/{sitekey}/conversation/{conversationid}/chat/stream":{"post":{"tags":["Conversations"],"operationId":"sendMessageStream","summary":"Send Message (Streaming)","description":"Sends the same request as Send a message, but streams progress and final-answer events using Server-Sent Events. Parse each data: line as JSON. The stream may emit progress updates, one final answer, then event: complete; failures after streaming begins arrive as event: error. A POST-capable SSE client or fetch streaming is required.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/ConversationId"},{"$ref":"#/components/parameters/Uid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"message":"Compare your two best-selling trail shoes"}}}},"responses":{"200":{"description":"Server-Sent Events stream. Progress and final-answer events contain JSON in data lines; event names may include complete and error.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"message\":\"Searching for best-selling trail running shoes...\"}\n\ndata: {\"message\":\"Here is how the two compare...\",\"products\":[],\"filters\":[],\"table_info\":[],\"show_products\":true}\n\nevent: complete\ndata: {}"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}},"/v1/sites/{sitekey}/conversation/{conversationid}/questions":{"post":{"tags":["Conversation Starters"],"operationId":"getConversationStarters","summary":"Get Conversation Starters","description":"Returns suggested questions for the current page and an optional welcome message.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/ConversationId"},{"$ref":"#/components/parameters/Uid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionsRequest"},"examples":{"productDetailPage":{"summary":"Product detail page","value":{"pagetype":"pdp","metadata":{"uniqueId":"SKU-2040"},"welcome_message":true}},"homePage":{"summary":"Home page","value":{"pagetype":"home","metadata":{}}}}}}},"responses":{"200":{"description":"Suggested questions returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionsResponse"},"example":{"welcome_message":"Hi! Looking at this product? I can help with sizing or comparisons.","questions":["Is this shoe true to size?","What socks go well with these?"]}},"text/plain":{"schema":{"type":"string"},"example":"No soup for you!"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}},"/v1/sites/{sitekey}/conversations":{"get":{"tags":["Conversations"],"operationId":"listConversations","summary":"List Conversations","description":"Returns the shopper's past conversations, suitable for a Recent chats list.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/Uid"}],"responses":{"200":{"description":"Conversations returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"},"example":{"conversations":[{"conversation_id":"6f1c2a8e-3b7d-4f0a-9c55-1e2d3f4a5b6c","created_at":"2026-10-14T09:21:07Z"}]}},"text/plain":{"schema":{"type":"string"},"example":"No soup for you!"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}},"/v1/sites/{sitekey}/conversation/{conversationid}":{"get":{"tags":["Conversations"],"operationId":"getConversationHistory","summary":"Get Conversation History","description":"Returns every message in a conversation, oldest first. Use the same conversation ID to continue the conversation with Send a message.","parameters":[{"$ref":"#/components/parameters/SiteKey"},{"$ref":"#/components/parameters/ConversationId"},{"$ref":"#/components/parameters/Uid"},{"$ref":"#/components/parameters/Products"}],"responses":{"200":{"description":"Conversation history returned, oldest message first.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HistoryMessage"}},"example":[{"role":"user","message":"I need running shoes under $100"},{"role":"assistant","message":"Here are some lightweight running shoes under $100...","products":[{"uniqueId":"SKU-1001","title":"Air Glide Runner","price":89.99}],"filters":[{"field":"brand","options":["Nike","Adidas","Asics"]}]}]},"text/plain":{"schema":{"type":"string"},"example":"No soup for you!"}}},"400":{"description":"Invalid request, such as missing uid, invalid JSON, or message longer than 1,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wrong path or HTTP method."},"500":{"description":"The assistant could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service temporarily unavailable or timed out."},"503":{"description":"Service temporarily unavailable."},"504":{"description":"Gateway timeout."}}}}},"components":{"securitySchemes":{"ShoppingAssistantToken":{"type":"apiKey","in":"header","name":"x-unx-sa-token","description":"API token issued by the Netcore Unbxd AI team. Keep this token server-side. The guide notes that a missing or invalid token may return HTTP 200 with text/plain body 'No soup for you!' rather than a 4xx response."}},"parameters":{"SiteKey":{"name":"sitekey","in":"path","required":true,"description":"Your site key, provided during onboarding. The site key is associated with a specific region.","schema":{"type":"string"}},"ConversationId":{"name":"conversationid","in":"path","required":true,"description":"Conversation ID returned by Start a conversation.","schema":{"type":"string"}},"Uid":{"name":"uid","in":"query","required":true,"description":"Stable identifier for the shopper. Use the same value that started the conversation.","schema":{"type":"string"}},"Products":{"name":"products","in":"query","required":false,"description":"Whether to include product cards in conversation history. Defaults to true.","schema":{"type":"boolean","default":true}}},"schemas":{"StartConversationResponse":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"ID of the new conversation. Store it and send it on every later call for this thread."}}},"ChatRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":1000,"description":"The shopper's message. Maximum 1,000 characters."},"image":{"type":"string","description":"Optional image for visual search: a public image URL, a data URL, or plain base64-encoded image data. Visual search must be enabled for the site."},"filters":{"type":"array","description":"Optional refinements selected from filters returned by a previous reply. Send only the new selections.","items":{"$ref":"#/components/schemas/Filter"}},"metadata":{"type":"array","description":"Optional integration-controlled product-search settings. Supported names are fields and filter; each value is an array of strings.","items":{"$ref":"#/components/schemas/MetadataItem"}}},"additionalProperties":true},"Filter":{"type":"object","required":["field","options"],"properties":{"field":{"type":"string","description":"Catalog attribute, such as brand, color, size, or price."},"options":{"type":"array","items":{"type":"string"},"description":"Available values in a response, or selected values in a request. The guide says to send one selected value per field."}},"additionalProperties":true},"MetadataItem":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","enum":["fields","filter"],"description":"Use fields to select returned catalog fields, or filter to apply Unbxd Search filter expressions."},"value":{"type":"array","items":{"type":"string"},"description":"Array of catalog field names or Unbxd Search filter expressions, depending on name."}},"additionalProperties":true},"Product":{"type":"object","description":"Product attributes mirror the catalog fields configured for the site. Fields can vary by site and may be absent.","properties":{"uniqueId":{"type":"string","description":"Product ID."},"title":{"type":"string","description":"Product name."},"price":{"oneOf":[{"type":"number"},{"type":"string"}],"description":"Display price."},"imageUrl":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}],"description":"Product image URL or URLs."},"productUrl":{"type":"string","format":"uri","description":"Link to the product page."}},"additionalProperties":true},"TableInfo":{"type":"object","required":["title","type","data"],"properties":{"title":{"type":"string","description":"Short heading for the table."},"type":{"type":"string","enum":["comparison","product_details","search_summary","variant_breakdown","document_info","planning"],"description":"Kind of table."},"data":{"type":"array","items":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number","nullable":true},{"type":"boolean","nullable":true}]}},"description":"Rows represented as objects mapping column names to cell values."}},"additionalProperties":true},"ChatResponse":{"type":"object","required":["message","products","filters"],"properties":{"message":{"type":"string","description":"Assistant reply. May contain Markdown."},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Products to show as cards; may be empty."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"},"description":"Suggested refinements; may be empty."},"table_info":{"type":"array","items":{"$ref":"#/components/schemas/TableInfo"},"description":"Optional structured tables, such as product comparisons."},"show_products":{"type":"boolean","description":"Streaming final-answer field. Show product cards only when true."}},"additionalProperties":true},"QuestionsRequest":{"type":"object","required":["pagetype","metadata"],"properties":{"pagetype":{"type":"string","enum":["home","search","category","pdp","cart"],"description":"Page the shopper is on."},"metadata":{"type":"object","description":"Page context. Required keys depend on pagetype: search requires query; category requires category_id; pdp requires uniqueId; cart requires uniqueIds; home can send an empty object.","additionalProperties":true},"welcome_message":{"type":"boolean","default":false,"description":"Set to true to also get a welcome message. Defaults to false."}},"additionalProperties":true},"QuestionsResponse":{"type":"object","required":["questions"],"properties":{"questions":{"type":"array","items":{"type":"string"},"description":"Suggested questions for this page."},"welcome_message":{"type":"string","description":"Greeting; present only when welcome_message=true was requested."}},"additionalProperties":true},"ConversationSummary":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"Conversation ID."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp in UTC (RFC 3339). May be omitted for older conversations."}},"additionalProperties":true},"ConversationListResponse":{"type":"object","required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}}}},"HistoryMessage":{"type":"object","required":["role","message"],"properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Speaker role."},"message":{"type":"string","description":"Message text."},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Assistant messages only; may be omitted if there were no product cards or products=false."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"},"description":"Assistant messages only, when filters were suggested."},"table_info":{"type":"array","items":{"$ref":"#/components/schemas/TableInfo"},"description":"Assistant messages only, when tables were shown."}},"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"Message":{"type":"string","description":"Error category."},"Code":{"type":"integer","description":"HTTP status code."},"Error":{"type":"string","description":"Detailed reason. Log it; do not show it to shoppers."}},"additionalProperties":true}}}}