{"openapi":"3.1.0","info":{"title":"ask.shopping API","version":"1.0.0","description":"REST API exposing the actions of the ask.shopping product. Authenticate with a Kavaro API key as a bearer token."},"servers":[{"url":"https://kavaro.ai"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"A Kavaro API key (user- or organization-scoped)."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/rest/actions/list_assistants":{"post":{"operationId":"list_assistants","summary":"List assistants","description":"List the organization's embeddable shopping assistants.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/get_assistant":{"post":{"operationId":"get_assistant","summary":"Get assistant","description":"Get one shopping assistant with its catalogue size, knowledge count, persona, model and embed key.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string","description":"The id of the assistant"}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/create_assistant":{"post":{"operationId":"create_assistant","summary":"Create assistant","description":"Create a new shopping assistant (an embeddable widget) for a storefront. Returns the assistant with its public embed key.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Display name, e.g. the brand or market"},"siteUrl":{"description":"The storefront URL to crawl for the catalogue","type":"string","format":"uri"},"persona":{"description":"Domain-expert persona / instructions for the assistant","type":"string"},"greeting":{"description":"First message shown when the widget opens","type":"string"},"modelName":{"description":"A tool-capable model name (see the model picker); defaults to a fast model","type":"string"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_assistant":{"post":{"operationId":"update_assistant","summary":"Update assistant","description":"Update a shopping assistant's name, status (draft/live), site URL, persona, greeting, model or branding.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["draft","live"]},"siteUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"persona":{"anyOf":[{"type":"string"},{"type":"null"}]},"greeting":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelName":{"type":"string"},"crawlUserAgent":{"anyOf":[{"type":"string"},{"type":"null"}]},"branding":{"description":"Public-facing look of the widget launcher and panel","type":"object","properties":{"primaryColor":{"type":"string"},"logoUrl":{"type":"string"},"launcherText":{"type":"string"}},"additionalProperties":false}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_assistant":{"post":{"operationId":"delete_assistant","summary":"Delete assistant","description":"Permanently delete a shopping assistant and its catalogue, knowledge and sessions.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/list_catalogue":{"post":{"operationId":"list_catalogue","summary":"List catalogue","description":"List the products discovered for an assistant's catalogue.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"},"search":{"description":"Filter by title/description/brand/category","type":"string"},"limit":{"type":"integer","minimum":1,"maximum":200}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/add_product":{"post":{"operationId":"add_product","summary":"Add product","description":"Manually add a product to an assistant's catalogue.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"externalId":{"description":"The host's own product id used by addToCart(id, amount)","type":"string"},"description":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"availability":{"type":"string","enum":["in_stock","out_of_stock","unknown"]},"imageUrl":{"type":"string","format":"uri"},"brand":{"type":"string"},"category":{"type":"string"}},"required":["assistantId","url","title"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_product":{"post":{"operationId":"update_product","summary":"Update product","description":"Update a catalogue product's details.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string"},"title":{"type":"string","minLength":1},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"availability":{"type":"string","enum":["in_stock","out_of_stock","unknown"]},"imageUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["productId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/remove_product":{"post":{"operationId":"remove_product","summary":"Remove product","description":"Remove a product from an assistant's catalogue.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string"}},"required":["productId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/start_crawl":{"post":{"operationId":"start_crawl","summary":"Crawl site","description":"Crawl the assistant's storefront to discover products. Uses microdata/JSON-LD by default, or AI pattern detection when structured data is absent. Returns the crawl run id; progress is tracked on the run.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"},"method":{"description":"microdata (default) or ai","type":"string","enum":["microdata","ai"]}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/list_crawls":{"post":{"operationId":"list_crawls","summary":"List crawls","description":"List an assistant's crawl runs with their status and counts.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/add_knowledge":{"post":{"operationId":"add_knowledge","summary":"Add knowledge","description":"Add a curated knowledge entry (guide, manual or note) that sharpens the in-chat advice.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"},"title":{"type":"string","minLength":1},"content":{"type":"string","minLength":1},"sourceType":{"type":"string","enum":["guide","manual","note"]}},"required":["assistantId","title","content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/list_knowledge":{"post":{"operationId":"list_knowledge","summary":"List knowledge","description":"List an assistant's curated knowledge entries.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["assistants:view"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assistantId":{"type":"string"}},"required":["assistantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/remove_knowledge":{"post":{"operationId":"remove_knowledge","summary":"Remove knowledge","description":"Remove a curated knowledge entry.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["catalogue:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"knowledgeId":{"type":"string"}},"required":["knowledgeId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}}}}