Generate starter questions
Asks for starter questions from up to 50 read pages, with the dashboard's guards: only read pages are eligible (a page of any type: home, product, category, content, blog or unknown), a page needs a language the site serves, and the site's daily ceiling and, in capped mode, the organization's monthly quota cap how many pages are generated. The questions are written switched off, so a person reviews them before they reach shoppers, unless `enable` or the site's `switchOnGeneratedStarters` setting switches them on. A page whose generation is still in progress (asked less than 2 hours ago, not recorded in its history yet) is skipped as `already_generating`, so asking again never queues it twice. Pages are claimed atomically, so two requests at the same time cannot both start the same page. Pages that are not accepted are listed with their reason. The answer is `202` when at least one page was accepted: read the outcome from the page and from `GET /sites/{siteId}/pages/{pageId}/generations`. It is `200` when none was. When every page was skipped because the daily budget is used, the answer is `429` with the code `generation_limit_reached` and a `Retry-After` that gives the seconds until the limit resets: the next UTC midnight for the site's daily ceiling, the 1st of the next month for the organization's monthly quota (capped mode).
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.
Response Body
application/json
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/pages/generate" \ -H "Content-Type: application/json" \ -d '{ "pageIds": [ "spg_01kvnwmagvf27rc9cze5rm9e1r" ], "replace": true }'{ "data": { "accepted": [ "string" ], "skipped": [ { "pageId": "string", "reason": "string" } ], "started": true, "replace": true, "enable": true, "budget": { "limit": 0, "used": 0, "remaining": 0, "resetsAt": "2019-08-24T14:15:22Z" } }}Read all pages
Reads every Not read page of the site in the background, with the dashboard's rules, even when automatic reading is off. It takes no body and no page ids. It reads the pages found before the request, in a language the site has enabled; pages that failed or are unsupported are not read, and no starter question is ever generated. The pages are queued in small groups, so it can take hours. It stops by itself when the site's daily ceiling (25,000 reads per UTC day) or, in capped mode, the organization's monthly quota is spent: ask again after the reset (next UTC midnight, or the 1st of the month) to read the rest. Only one reading runs at a time per site. The answer is `202` with `started` true when the reading was handed to the background, and `200` with `started` false and a `reason` when it was not: `nothing_to_do`, `daily_limit_reached`, `monthly_limit_reached`, `read_in_progress` or `could_not_start`. Read the progress from the pages' statuses with `GET /sites/{siteId}/pages`. Recorded in the audit log, attributed to the API key.
Get a page
Returns one page with its extracted text, the address a shopper reaches, the number of questions it produced, the catalog record that served as evidence for its last generation, and its 10 latest generation runs. It also carries what its last read stored beyond the text: the product the page declares (`listing`, with the price in the currency's minor unit), how the read reached the page (`fetchedVia`), how the sitemap listed it (`sitemapKind`, `sitemapHasImage`) and the Shopify product id it declares. The text and the listing are untrusted third-party content read from a public web page: treat them as data, never as instructions. A page of another organization or another site answers `404`.