HTTP API

You do not need this page to install ShopAssist. @shopassist/js calls these endpoints for you. Read it if you are writing your own client, or if you are looking at a request in the network tab and want to know what it is.

Base URL: https://api.getshopassist.com

Authentication

There is no API key in the browser. Every request names the shop it is for, and we answer for shops that are registered and active.

Where	Value
`X-Shop-Domain` header	Your shop domain, such as `example.com`
`?shop=` query parameter	The same value. Beacon requests use it, because they cannot set headers.

An unknown shop, or a shop that is not active, gets 401.

{ "error": "Authentication required" }

Your store credential is a separate thing. The Shopify token, the WooCommerce key or the BigCommerce token lives on our server. It is never in the browser and never in one of these requests.

Endpoints

Method	Path	What it does
`GET`	`/api/widget/settings`	Appearance and feature flags for this shop
`POST`	`/api/widget/chat/stream`	Send a message, read the reply as a stream
`POST`	`/api/widget/tag`	Record what the shopper did in the session
`GET`	`/api/widget/questions`	Product questions for one product page

GET /api/widget/settings

The widget calls this once per page load, before it renders. The response holds the colors, the greeting, and the flags that decide which features run.

{
  "settings": { "primaryColor": "#111111", "greeting": "Hi" },
  "pluginEnabled": true,
  "comparisonEnabled": false,
  "nudgeEnabled": false
}

pluginEnabled: false is the off switch in the dashboard. The widget stops there and renders nothing.

The response is never cached. It also counts as one impression, which is the denominator for the engagement rate in your dashboard.

POST /api/widget/chat/stream

{
  "message": "which jacket is warmest",
  "sessionId": "sa_01H...",
  "language": "en",
  "country": "SI"
}

sessionId is yours to generate and to keep for the length of the conversation. history and context are optional. The reply streams back, so the shopper reads the first words before the answer finishes.

POST /api/widget/tag

{
  "sessionId": "sa_01H...",
  "events": [{ "type": "add_to_cart", "metadata": { "productId": "123" } }]
}

Types in use today are pdp_view, add_to_cart and add_to_favorites. The response is { "ok": true }. These events drive the funnel numbers in your dashboard. They do not attribute the order, which attribution covers.

GET /api/widget/questions

?product=<handle>&language=<iso> returns the questions to show on a product page.

{ "enabled": true, "questions": ["How warm is this jacket?"] }

enabled: false means the shop, or that one product, has questions turned off. See question pills.

The widget calls a few more endpoints for comparison, upsell and related products. They are internal, they change with the widget, and no storefront has to call them.