iAdvizeDocs

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, and `meta.matching` counts the questions the filters leave. 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 and the sort it was issued for.

GET
/api/v1/sites/{siteId}/starter-questions

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

Query Parameters

source?string

Only questions with this source. generated is both kinds of generated question together (ai_generated and ai_generated_edited).

Value in

  • "manual"
  • "ai_generated"
  • "ai_generated_edited"
  • "generated"
state?string

Only questions in this state.

Value in

  • "live"
  • "partial"
  • "needs_setup"
  • "offline"
verdict?string

Only questions with this performance verdict over the 14-day window.

Value in

  • "never_shown"
  • "not_enough_data"
  • "promising"
  • "workhorse"
  • "underperforming"
enabled?boolean

true for switched-on questions, false for switched-off ones.

search?string

Questions whose label or message, in any language, or the address of the page they were generated from, contains this text. Case does not matter, and %, _ and \ are literal. At most 200 characters.

Lengthlength <= 200
reachesPageType?string

Questions shown on this page type: a question shown on all pages reaches every type, and a question that targets page types reaches the ones it lists.

Value in

  • "home"
  • "product"
  • "category"
  • "content"
  • "blog"
language?string

A language the site has enabled. By default the questions that have text in it; with languageMatch=missing, the questions that have none. A language the site has not enabled is refused with language_not_enabled.

Value in

  • "fr"
  • "en"
  • "de"
  • "it"
  • "es"
  • "nl"
languageMatch?string

With language: has (the default) for the questions that have text in it, missing for the questions that lack it. Needs language.

Value in

  • "has"
  • "missing"
sort?string

The order of the list: position (the library's own order, the one shoppers get questions in, by default), updated (last modified), state (live, partial, needs setup, offline), click_rate (questions never shown come last in either direction) or performance (underperforming, promising, not enough data, workhorse, never shown). Questions that tie keep the library's order.

Default"position"

Value in

  • "position"
  • "updated"
  • "state"
  • "click_rate"
  • "performance"
order?string

asc (the default) or desc, for the sort.

Default"asc"

Value in

  • "asc"
  • "desc"
pageId?string

Only questions generated from this page.

appliesToPath?string

The shopper's path, with its query string if any, or a full address of the shop. Needs appliesToLanguage.

appliesToPageType?string

The page type the page declares. Omit it for a page that declares none.

Value in

  • "home"
  • "product"
  • "category"
  • "content"
  • "blog"
appliesToLanguage?string

The shopper's language. Needs appliesToPath.

Value in

  • "fr"
  • "en"
  • "de"
  • "it"
  • "es"
  • "nl"
cursor?string

The meta.nextCursor of the previous page, with the same filters.

limit?integer

The page size, 1 to 100.

Range1 <= value <= 100
Default50

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/api/v1/sites/string/starter-questions"
{  "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": "ai_generated",      "sourcePageId": "spg_01kvnwmagvf27rc9cze5rm9e1r",      "generatedAt": "2026-10-03T09:00:12.000Z",      "createdAt": "2026-10-03T09:00:12.000Z",      "updatedAt": "2026-10-03T09:00:12.000Z",      "state": {        "value": "live",        "reason": null,        "missingLanguages": []      },      "performance": {        "windowDays": 14,        "impressions": 240,        "clicks": 36,        "clickRate": 0.15,        "verdict": "workhorse",        "reason": null      }    }  ],  "meta": {    "nextCursor": null,    "matching": 1,    "totals": {      "total": 1,      "byState": {        "live": 1,        "partial": 0,        "needs_setup": 0,        "offline": 0      },      "bySource": {        "manual": 0,        "ai_generated": 1,        "ai_generated_edited": 0      }    }  }}

List a site's most viewed pages over the last 30 days

Returns the pages of the site with a view in the last 30 UTC days, most viewed first, at most 50. These are the figures of the Page views tab of the Engagement report and of the Views column of the Pages list. Pages with no view in the window are left out, and there is no paging, cursor or filter. The figures are computed once a day, so `meta.computedAt` says when they were last computed (`null` before the first computation). `meta.countingOn` is `false` while page-view counting is off for the site: `data` is then empty, and that is not the same as no page being viewed. Switch counting on under Settings, Site access.

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. A question with a `*` wildcard pattern is refused with `wildcard_question_limit_reached` once the site holds 100 of them, switched on or off; nothing is changed then.