{"openapi":"3.1.0","info":{"title":"BehaviorGPT shopping API","description":"BehaviorGPT's shopping calls: search suggestions, search results, category pages,\nshelves, titled sections, an item and a search by picture, each ranked for one\nshopper. The same answers the portal's widgets show.\n\n**From a server**, send your API key: `Authorization: Bearer ubx_...`. Keep it there.\n\n**From an app** with no server of its own, call `https://portal.unboxai.com/api/widgets/v1/`\nand the same path instead, with the same body plus `key`, a publishable key\n(`ubx_pub_...`) that lists the app, and the app's id in the `X-Unbox-App` header\n(its bundle id, such as `com.example.shop`). Send the body as `text/plain` or\n`application/json`.\n\n`user` is your id for the shopper, the one their events are recorded under: their\nrecorded searches and views come first. `history` (oldest first) adds what they did\nthat is not recorded yet. Nothing a call asks is recorded.\n","version":"1.0.0"},"servers":[{"url":"https://portal.unboxai.com"}],"paths":{"/api/v1/shop/suggest":{"post":{"summary":"Search suggestions as the shopper types","description":"What this shopper likely wants for the text so far, as short searches: an item's keywords, or its name made a phrase. With empty `text`, what they likely search next.","operationId":"shop_suggest_api_v1_shop_suggest_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"text":{"type":"string","maxLength":100,"title":"Text","default":""},"limit":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Limit","default":6}},"type":"object","required":["catalog"],"title":"SuggestAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestions"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/search":{"post":{"summary":"Search results, a page at a time","description":"The results for `query`, best for this shopper first, `limit` from `offset`. `more` says whether there is another page. `only` keeps them to categories, brands or prices.","operationId":"shop_search_api_v1_shop_search_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"only":{"anyOf":[{"$ref":"#/components/schemas/Only"},{"type":"null"}]},"query":{"type":"string","maxLength":200,"minLength":1,"title":"Query"},"limit":{"type":"integer","maximum":48.0,"minimum":1.0,"title":"Limit","default":12},"offset":{"type":"integer","maximum":480.0,"minimum":0.0,"title":"Offset","default":0}},"type":"object","required":["catalog","query"],"title":"SearchAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/browse":{"post":{"summary":"A category page","description":"The items `only` admits (a category, brand or price), best for this shopper first. A shopper nothing is known about gets the category's best for anyone.","operationId":"shop_browse_api_v1_shop_browse_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"only":{"$ref":"#/components/schemas/Only"},"limit":{"type":"integer","maximum":48.0,"minimum":1.0,"title":"Limit","default":12},"offset":{"type":"integer","maximum":480.0,"minimum":0.0,"title":"Offset","default":0}},"type":"object","required":["catalog","only"],"title":"BrowseAsk","description":"A category page: the items `only` admits, best for the visitor first."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/recommend":{"post":{"summary":"A shelf","description":"`for_you`: what the shopper likely wants next. `similar`: what people view after `item`. `bought_together`: what goes in the same purchase as `item`, one product of each kind, each with its kind's name as `tag`. `cart`: what goes with `items`. `after_purchase`: what the shopper wants next now that they bought `items`, one of each kind. No shelf shows what the shopper viewed or bought, or one product twice.","operationId":"shop_recommend_api_v1_shop_recommend_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"only":{"anyOf":[{"$ref":"#/components/schemas/Only"},{"type":"null"}]},"kind":{"type":"string","enum":["for_you","similar","bought_together","cart","after_purchase"],"title":"Kind","default":"for_you"},"item":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Item"},"items":{"items":{"type":"string","maxLength":200},"type":"array","maxItems":20,"title":"Items","default":[]},"limit":{"type":"integer","maximum":24.0,"minimum":1.0,"title":"Limit","default":8}},"type":"object","required":["catalog"],"title":"RecommendAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Items"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/sections":{"post":{"summary":"Titled shelves, best first","description":"What the shopper likely wants next, or with `query` its results, grouped under titles such as \"Linen sofas\". The titles come from the catalog's keywords, so a catalog without them has none.","operationId":"shop_sections_api_v1_shop_sections_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"only":{"anyOf":[{"$ref":"#/components/schemas/Only"},{"type":"null"}]},"query":{"type":"string","maxLength":200,"title":"Query","default":""},"sections":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Sections","default":4},"limit":{"type":"integer","maximum":24.0,"minimum":1.0,"title":"Limit","default":8}},"type":"object","required":["catalog"],"title":"SectionsAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sections"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/item":{"post":{"summary":"One item, with its keywords","description":"The item's card and its search terms, best first.","operationId":"shop_item_api_v1_shop_item_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"item":{"type":"string","maxLength":200,"minLength":1,"title":"Item"}},"type":"object","required":["catalog","item"],"title":"ItemAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneItem"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/visual":{"post":{"summary":"Search by picture: a data: URL or base64 as `image`, or a link as `url`","description":"The catalog's items that look most like a picture: a photo, a screenshot, or a link to a picture or to any page showing one. A picture BehaviorGPT has read before answers at once (`status: ready`); a new one answers `pending` or `embedding` with a `picture` id to pass to `/visual/status`.","operationId":"shop_visual_api_v1_shop_visual_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"image":{"anyOf":[{"type":"string","maxLength":8000000},{"type":"null"}],"title":"Image"},"url":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Url"},"words":{"type":"string","maxLength":200,"title":"Words","default":""},"kind":{"type":"string","enum":["look","for_you"],"title":"Kind","default":"look"},"limit":{"type":"integer","maximum":48.0,"minimum":1.0,"title":"Limit","default":12}},"type":"object","required":["catalog"],"title":"VisualAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Picture"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/shop/visual/status":{"post":{"summary":"A picture BehaviorGPT is still reading: ask every second or two until `ready`","description":"The answer to a `/visual` call that was not ready yet, for the `picture` it returned: the same items once BehaviorGPT has read the picture.","operationId":"shop_visual_status_api_v1_shop_visual_status_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalog":{"type":"string","maxLength":100,"minLength":1,"title":"Catalog"},"user":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"User"},"history":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","maxItems":20,"title":"History","default":[]},"who":{"anyOf":[{"$ref":"#/components/schemas/Who"},{"type":"null"}]},"picture":{"type":"string","maxLength":60,"title":"Picture"},"kind":{"type":"string","enum":["look","for_you"],"title":"Kind","default":"look"},"limit":{"type":"integer","maximum":48.0,"minimum":1.0,"title":"Limit","default":12}},"type":"object","required":["catalog","picture"],"title":"VisualStatusAsk"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Picture"}}}},"400":{"description":"The body is not a call: what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No live API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A catalog or item the key cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Past the account's limit a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"apiKey":[]}]}}},"components":{"schemas":{"Card":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"keywords":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Keywords"},"tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag"},"exact":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Exact"}},"type":"object","required":["id","name"],"title":"Card","description":"An item as every call shows it."},"Items":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Card"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"Items"},"OneItem":{"properties":{"item":{"$ref":"#/components/schemas/Card"}},"type":"object","required":["item"],"title":"OneItem"},"Page":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Card"},"type":"array","title":"Items"},"offset":{"type":"integer","title":"Offset"},"more":{"type":"boolean","title":"More"}},"type":"object","required":["items","offset","more"],"title":"Page"},"Picture":{"properties":{"picture":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Picture"},"status":{"type":"string","enum":["pending","embedding","ready","failed"],"title":"Status"},"phase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/Card"},"type":"array"},{"type":"null"}],"title":"Items"}},"type":"object","required":["picture","status"],"title":"Picture","description":"A search by picture: its products once BehaviorGPT has read it. While it\nis `pending` or `embedding`, ask `visual/status` with `picture` again."},"Problem":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"Problem"},"Section":{"properties":{"title":{"type":"string","title":"Title"},"items":{"items":{"$ref":"#/components/schemas/Card"},"type":"array","title":"Items"}},"type":"object","required":["title","items"],"title":"Section"},"Sections":{"properties":{"sections":{"items":{"$ref":"#/components/schemas/Section"},"type":"array","title":"Sections"}},"type":"object","required":["sections"],"title":"Sections"},"Suggestion":{"properties":{"text":{"type":"string","title":"Text"},"source":{"type":"string","title":"Source"},"item":{"type":"string","title":"Item"}},"type":"object","required":["text","source","item"],"title":"Suggestion"},"Suggestions":{"properties":{"suggestions":{"items":{"$ref":"#/components/schemas/Suggestion"},"type":"array","title":"Suggestions"}},"type":"object","required":["suggestions"],"title":"Suggestions"},"Event":{"description":"Something the visitor did on this page that may not be recorded yet.","properties":{"type":{"enum":["search","view"],"title":"Type","type":"string"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"title":"Query"},"item":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"title":"Item"}},"required":["type"],"title":"Event","type":"object"},"Who":{"description":"Who the visitor is, as the tracking script's `profile` takes it.","properties":{"gender":{"anyOf":[{"enum":["female","male"],"type":"string"},{"type":"null"}],"title":"Gender"},"age_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age Group"},"market":{"anyOf":[{"pattern":"^[A-Za-z]{2}$","type":"string"},{"type":"null"}],"title":"Market"},"timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"title":"Timezone"}},"title":"Who","type":"object"},"Only":{"additionalProperties":false,"description":"Which items a ranking may show: in any of `categories` (at any level of an\nitem's category path), of any of `brands`, priced within the bounds. Each\ngiven condition must hold; values are matched exactly, as the catalog has them.","properties":{"categories":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":10,"title":"Categories","type":"array"},"brands":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":10,"title":"Brands","type":"array"},"min_price":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"title":"Min Price"},"max_price":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"title":"Max Price"}},"title":"Only","type":"object"}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key, ubx_..."}}}}