Assistant · API reference

10 endpoints.

POST /v1/assistant/chat
GET /v1/assistant/widget
GET /v1/assistant/settings
PUT /v1/assistant/settings
GET /v1/assistant/conversations
GET /v1/assistant/conversations/{conversation_id}
GET /v1/assistant/knowledge
POST /v1/assistant/knowledge
PUT /v1/assistant/knowledge/{doc_id}
DELETE /v1/assistant/knowledge/{doc_id}

POST/v1/assistant/chat

Shopping assistant (public key with the `assistant` scope)

Needs a key or a dashboard session

Request body `application/json` `ChatRequest`

Name	Type	Required	Description
`conversation_id`	`string \| null`	no	Omit to start a new conversation.
`message`	`string`	yes	min length 1 · max length 2000
`locale`	`string`	no	default "ar" · pattern ^[a-z]{2}$
`session`	`string \| null`	no	max length 64
`context`	`map<string, string>`	no	e.g. current product id or category page.
`stream`	`boolean`	no	true = text/event-stream of ChatEvent objects.default false

Responses

200JSON, or SSE when stream=trueChatResponse

GET/v1/assistant/widget

Chat widget setup: on/off, white-label name, greeting (public key with the `assistant` scope)

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`locale`	`query`	`string`	no	default "ar" · pattern ^[a-z]{2}$

Responses

200Successful ResponseAssistantWidgetConfig

GET/v1/assistant/settings

Assistant Settings Get

Needs a key or a dashboard session

Responses

200Successful ResponseAssistantSettings-Output

PUT/v1/assistant/settings

Assistant Settings Put

Needs a key or a dashboard session

Request body `application/json` `AssistantSettings-Input`

Name	Type	Required	Description
`enabled`	`boolean`	no	default false
`display_name`	`string`	no	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	no	default "friendly"
`locales`	`string[]`	no
`handover`	`map<string, string>`	no	whatsapp/phone/email targets.
`monthly_budget_usd`	`number \| string \| null`	no	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.min 0
`greeting`	`map<string, string>`	no

Responses

200Successful ResponseAssistantSettings-Output

GET/v1/assistant/conversations

Assistant Conversations List

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`cursor`	`query`	`string \| null`	no	max length 200
`limit`	`query`	`integer`	no	default 50 · min 1 · max 200

Responses

200Successful ResponsePage_ConversationSummary_

GET/v1/assistant/conversations/{conversation_id}

Assistant Conversations Get

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	`string`	yes

Responses

200Successful ResponseConversationDetail

GET/v1/assistant/knowledge

Store FAQ and policies the assistant may use

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`cursor`	`query`	`string \| null`	no	max length 200
`limit`	`query`	`integer`	no	default 100 · min 1 · max 200

Responses

200Successful ResponsePage_KnowledgeDocOut_

POST/v1/assistant/knowledge

Knowledge Create

Needs a key or a dashboard session

Request body `application/json` `KnowledgeDocIn`

Name	Type	Required	Description
`kind`	`"faq" \| "policy" \| "page"`	yes
`locale`	`string`	yes	pattern ^[a-z]{2}$
`title`	`string`	yes	max length 300
`content`	`string`	yes	max length 50000
`url`	`string \| null`	no	max length 2048

Responses

201Successful ResponseKnowledgeDocOut

PUT/v1/assistant/knowledge/{doc_id}

Knowledge Update

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`doc_id`	`path`	`string`	yes

Request body `application/json` `KnowledgeDocIn`

Name	Type	Required	Description
`kind`	`"faq" \| "policy" \| "page"`	yes
`locale`	`string`	yes	pattern ^[a-z]{2}$
`title`	`string`	yes	max length 300
`content`	`string`	yes	max length 50000
`url`	`string \| null`	no	max length 2048

Responses

200Successful ResponseKnowledgeDocOut

DELETE/v1/assistant/knowledge/{doc_id}

Knowledge Delete

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`doc_id`	`path`	`string`	yes

Responses

200Successful ResponseDeleted

Data shapes on this page

ChatRequest

Name	Type	Required	Description
`conversation_id`	`string \| null`	no	Omit to start a new conversation.
`message`	`string`	yes	min length 1 · max length 2000
`locale`	`string`	no	default "ar" · pattern ^[a-z]{2}$
`session`	`string \| null`	no	max length 64
`context`	`map<string, string>`	no	e.g. current product id or category page.
`stream`	`boolean`	no	true = text/event-stream of ChatEvent objects.default false

ChatResponse

Name	Type	Required	Description
`conversation_id`	`string`	yes
`message_id`	`string`	yes
`answer`	`string`	yes
`products`	`ProductCard[]`	no	Live prices and stock from the index.
`comparison`	`object \| null`	no	Table when comparing 2-4 products.
`sources`	`Source[]`	no
`follow_up_questions`	`string[]`	no
`handover`	`Handover \| null`	no
`refused`	`"off_topic" \| "injection" \| "budget" \| "unavailable" \| null`	no

ProductCard

Display fields. Connectors that render their own cards use only `id`.

Name	Type	Required
`id`	`string`	yes
`name`	`map<string, string>`	yes
`url`	`string \| null`	no
`image_url`	`string \| null`	no
`price`	`string`	yes
`sale_price`	`string \| null`	no
`currency`	`string`	yes
`in_stock`	`boolean`	yes
`brand`	`string \| null`	no
`category`	`map<string, string> \| null`	no

Source

Name	Type	Required	Description
`type`	`"product" \| "faq" \| "policy" \| "page"`	yes
`id`	`string`	yes
`title`	`string \| null`	no
`fields`	`string[]`	no	Catalog fields the answer used (price, size, ...).

Handover

Name	Type	Required
`channel`	`"whatsapp" \| "phone" \| "email"`	yes
`url`	`string \| null`	no
`summary`	`string`	yes

AssistantWidgetConfig

What the shopper-side chat widget needs (public key, `assistant` scope). No budget, no targets.

Name	Type	Required	Description
`enabled`	`boolean`	yes	false: the widget hides the chat button.
`display_name`	`string`	yes	White-label name, e.g. "Ask Store" (default "Ask <store name>").
`greeting`	`string`	yes
`locale`	`string`	yes
`handover_channels`	`"whatsapp" \| "phone" \| "email"[]`	no

AssistantSettings-Output

Name	Type	Required	Description
`enabled`	`boolean`	no	default false
`display_name`	`string`	no	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	no	default "friendly"
`locales`	`string[]`	no
`handover`	`map<string, string>`	no	whatsapp/phone/email targets.
`monthly_budget_usd`	`string \| null`	no	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.
`greeting`	`map<string, string>`	no

AssistantSettings-Input

Name	Type	Required	Description
`enabled`	`boolean`	no	default false
`display_name`	`string`	no	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	no	default "friendly"
`locales`	`string[]`	no
`handover`	`map<string, string>`	no	whatsapp/phone/email targets.
`monthly_budget_usd`	`number \| string \| null`	no	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.min 0
`greeting`	`map<string, string>`	no

Page_ConversationSummary_

Name	Type	Required	Description
`data`	`ConversationSummary[]`	yes
`next_cursor`	`string \| null`	no
`total`	`integer \| null`	no	Present when cheap to count.

ConversationSummary

Name	Type	Required
`id`	`string`	yes
`locale`	`string`	yes
`started_at`	`string (date-time)`	yes
`message_count`	`integer`	yes
`handover`	`string`	yes
`clicked`	`boolean`	yes
`cost_usd`	`string`	yes

ConversationDetail

Name	Type	Required
`id`	`string`	yes
`locale`	`string`	yes
`started_at`	`string (date-time)`	yes
`message_count`	`integer`	yes
`handover`	`string`	yes
`clicked`	`boolean`	yes
`cost_usd`	`string`	yes
`messages`	`ConversationMessage[]`	yes
`summary`	`string \| null`	no

ConversationMessage

Name	Type	Required
`id`	`string`	yes
`role`	`"user" \| "assistant"`	yes
`content`	`string`	yes
`sources`	`Source[]`	no
`product_ids`	`string[]`	no
`flagged`	`string \| null`	no
`created_at`	`string (date-time)`	yes

Page_KnowledgeDocOut_

Name	Type	Required	Description
`data`	`KnowledgeDocOut[]`	yes
`next_cursor`	`string \| null`	no
`total`	`integer \| null`	no	Present when cheap to count.

KnowledgeDocOut

Name	Type	Required	Description
`kind`	`"faq" \| "policy" \| "page"`	yes
`locale`	`string`	yes	pattern ^[a-z]{2}$
`title`	`string`	yes	max length 300
`content`	`string`	yes	max length 50000
`url`	`string \| null`	no	max length 2048
`id`	`string`	yes
`updated_at`	`string (date-time)`	yes

KnowledgeDocIn

Name	Type	Required	Description
`kind`	`"faq" \| "policy" \| "page"`	yes
`locale`	`string`	yes	pattern ^[a-z]{2}$
`title`	`string`	yes	max length 300
`content`	`string`	yes	max length 50000
`url`	`string \| null`	no	max length 2048

Deleted

Name	Type	Required	Description
`deleted`	`boolean`	no	default true
`id`	`string`	yes

Request body application/json ChatRequest

Responses

Parameters

Responses

Responses

Request body application/json AssistantSettings-Input

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Request body application/json KnowledgeDocIn

Responses

Parameters

Request body application/json KnowledgeDocIn

Responses

Parameters

Responses

Data shapes on this page

ChatRequest

ChatResponse

ProductCard

Source

Handover

AssistantWidgetConfig

AssistantSettings-Output

AssistantSettings-Input

Page_ConversationSummary_

ConversationSummary

ConversationDetail

ConversationMessage

Page_KnowledgeDocOut_

KnowledgeDocOut

KnowledgeDocIn

Deleted

Request body `application/json` `ChatRequest`

Request body `application/json` `AssistantSettings-Input`

Request body `application/json` `KnowledgeDocIn`

Request body `application/json` `KnowledgeDocIn`