Widget preflight

get/v1/widget/preflight

Tells an embed whether the widget can be shown for the organization behind the public key, and hands back everything it needs to do so: the resolved theme colours and an analytics session token. The Stylor embed script calls this once per page load; call it yourself if you host your own launcher.

Readiness

ready is true when the organization has at least one active dataset. When you pass datasetIds, readiness is judged on those datasets instead: ready is true if at least one of them belongs to your organization and is not archived, so a scope made only of draft datasets is ready. This is the same rule search applies to an explicit datasetIds. Otherwise ready is false with a reason, the HTTP status is still 200, and no session is issued — there is nothing to measure if the widget is not shown. The theme is returned in both cases.

Theme

The flat theme object holds the colours and launcher label the widget should render with. It is resolved in this order: the preset named by themeId if it belongs to your organization; otherwise your most recently modified preset; otherwise Stylor's defaults. An unknown themeId is not an error — it silently falls through to the next rule. Any colour a preset leaves unset falls back to the default for that key.

Analytics session

session.token is the credential for the events endpoint. Send it as the X-Stylor-Session header on every POST /v1/events. It is bound to your organization and, when the request carried an Origin header, to that storefront origin. It expires after expiresIn seconds (two hours); calling preflight again issues a fresh one.

Pass the previous session.sessionId back as sid on the next page load so a shopper browsing several pages stays one session. A sid that is not a UUID is ignored and a new id is minted. session is null when the server cannot sign tokens; the widget still loads, it simply sends no analytics.

CORS

The route answers OPTIONS preflight with 204 and allows any origin, so it can be called directly from a storefront page.

Public keyapi.v1.widget.preflightDemo key OK

Query parameters

themeIdstring

Id of a widget theme preset belonging to your organization. Falls back to the most recently modified preset, then to defaults, when absent or unknown.

datasetIdsstring

Comma-separated dataset ids the widget is scoped to. When present, readiness counts these datasets (draft included, archived excluded) instead of the organization's active datasets. At most 50 ids are read.

sidstring (uuid)

The session.sessionId from an earlier preflight in the same browser tab, so navigation within the store stays one visit. Must be a UUID; anything else is ignored and a new session id is minted.

Headers

Originstring

Set automatically by browsers. When present it is recorded in the session token, and later event batches from a different origin are refused.

Response

200Readiness, theme and (when ready) the analytics session.

readybooleanrequired

true when the organization has at least one active dataset and the widget may be shown.

e.g. true

reasonstring

Only present when ready is false. Currently always No active datasets found for this organization.

e.g. "No active datasets found for this organization."

WidgetThemerequired

Flat set of colours (CSS hex) and the launcher label. Every key is always present; unset preset values fall back to the defaults shown.

buttonBgstringrequired

Launcher button background.

default: "#2D2926"

buttonHoverstringrequired

Launcher button background on hover.

default: "#231F1C"

buttonTextstringrequired

Launcher button text colour.

default: "#FFFFFF"

buttonLabelstringrequired

Launcher button label.

default: "Talk to stylist"

typingDotstringrequired

Colour of the typing indicator dots.

default: "#2D2926"

accentstringrequired

Primary accent inside the panel.

default: "#2D2926"

accentHoverstringrequired

Accent on hover.

default: "#4B4641"

textMutedstringrequired

Secondary text colour.

default: "#434656"

textPrimarystringrequired

Primary text colour.

default: "#1B1C1A"

bgPagestringrequired

Panel page background.

default: "#FFFFFF"

bgSurfacestringrequired

Card and surface background.

default: "#FBF9F5"

borderstringrequired

Border colour.

default: "#C4C5D9"

inputBgstringrequired

Message input background.

default: "#F5F3EF"

footerBgstringrequired

Panel footer background.

default: "#FFFFFF"

WidgetSession | nullnullable

Present only when ready is true. null when the server cannot issue tokens; the widget should then send no analytics.

Option 1: WidgetSession

tokenstringrequired

Signed session token. Send as X-Stylor-Session on POST /v1/events.

e.g. "eyJ2IjoxLCJzaWQiOiI0ZDJhOWMxZS03YjNmLTRlOGEtOWM2ZC0xZjJlM2E0YjVjNmQiLCJvcmciOiIw..."

sessionIdstring (uuid)required

The session id, lowercase. Equal to sid when a valid one was passed, otherwise newly minted. Pass it back as sid on subsequent page loads.

e.g. "4d2a9c1e-7b3f-4e8a-9c6d-1f2e3a4b5c6d"

expiresInintegerrequired

Seconds until the token expires. Always 7200.

e.g. 7200

Option 2: null

Errors

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

This endpoint has no errors of its own beyond the shared set below.

curl -X GET "https://stylor.ai/api/v1/widget/preflight" \
  -H "Authorization: Bearer $STYLOR_API_KEY"

Response · 200

{
  "ready": true,
  "theme": {
    "buttonBg": "#2D2926",
    "buttonHover": "#231F1C",
    "buttonText": "#FFFFFF",
    "buttonLabel": "Talk to stylist",
    "typingDot": "#2D2926",
    "accent": "#2D2926",
    "accentHover": "#4B4641",
    "textMuted": "#434656",
    "textPrimary": "#1B1C1A",
    "bgPage": "#FFFFFF",
    "bgSurface": "#FBF9F5",
    "border": "#C4C5D9",
    "inputBg": "#F5F3EF",
    "footerBg": "#FFFFFF"
  },
  "session": {
    "token": "eyJ2IjoxLCJzaWQiOiI0ZDJhOWMxZS03YjNmLTRlOGEtOWM2ZC0xZjJlM2E0YjVjNmQiLCJvcmciOiIw...",
    "sessionId": "4d2a9c1e-7b3f-4e8a-9c6d-1f2e3a4b5c6d",
    "expiresIn": 7200
  }
}