Create a starter question
Writes a question at the head of the library. It is live at once, as in the dashboard, unless you send `enabled: false`. It is always hand-written: the request cannot set a source or a source page, and such fields are ignored. A language the site does not serve is refused with `language_not_enabled` and nothing is written. Limits: a label of 1 to 60 characters, a message of up to 500, and up to 10 URL patterns.
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Path Parameters
The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A question is always written as a hand-written one: a request cannot set its source, the page it came from or any other provenance, and such fields are ignored.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/api/v1/sites/string/starter-questions" \ -H "Content-Type: application/json" \ -d '{ "texts": { "en": { "label": "Is it waterproof?", "message": "Is the trail shoe waterproof?" } }, "targeting": { "mode": "page_types", "pageTypes": [ "product" ] } }'{ "data": { "id": "stq_01kvnwmagvf27rc9cze5rm9e1r", "position": -3, "enabled": true, "targeting": { "mode": "url_patterns", "pageTypes": [], "urlPatterns": [ "products/trail-shoe" ] }, "texts": { "en": { "label": "Is it waterproof?", "message": null } }, "source": "manual", "sourcePageId": null, "generatedAt": null, "createdAt": "2026-10-03T09:00:12.000Z", "updatedAt": "2026-10-03T09:00:12.000Z", "state": { "value": "live", "reason": null, "missingLanguages": [] }, "performance": { "windowDays": 14, "impressions": 0, "clicks": 0, "clickRate": null, "verdict": "never_shown", "reason": "too_recent" }, "surfaces": [ { "surface": "welcome_screen", "impressions": 0, "clicks": 0, "clickRate": null }, { "surface": "composer", "impressions": 0, "clicks": 0, "clickRate": null }, { "surface": "launcher", "impressions": 0, "clicks": 0, "clickRate": null }, { "surface": "starters", "impressions": 0, "clicks": 0, "clickRate": null } ], "daily": [] }}List a site's starter questions
Returns the site's library in its own order, each question with the state and the 14-day performance the dashboard shows. The totals by state and by source count the whole library whatever the filters. To see what a shopper is offered on a page, send `appliesToPath` and `appliesToLanguage` (and `appliesToPageType` when the page declares one). The list then holds the switched-on questions that match the page's targeting and have text in that language, in display order, at most three as on the storefront. A page that declares no type is offered the questions that target page types, as on the storefront. Filters combine with AND. `limit` is 1 to 100 (50 by default), and a cursor is bound to the filters it was issued for.
Get a starter question
Returns one question with its state and 14-day performance, plus the same impressions and clicks per surface and per UTC day. A question of another organization or another site answers `404`.