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. 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
/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.

Value in

  • "manual"
  • "ai_generated"
  • "ai_generated_edited"
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.

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"
  • "category"
  • "product"
  • "checkout"
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,    "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 page's generation runs

Returns the runs that asked for starter questions from this page, newest first, up to `limit`. Each run says how it ended and why, and which catalog record served as evidence. It carries nothing about cost or usage.

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.