Read pages
Queues up to 50 pages for a read, within the read budget (the site's daily ceiling and, in capped mode, the organization's monthly quota): a discovered page for the first time, any other page again. With `generateAfter`, starter questions are generated for each page that ends read, within the generation budget, and arrive switched off; `replace` says whether they replace the page's earlier generated questions (the default) or are added beside them. A page that is already being read is skipped and reported as `already_reading`, and an id that is not a page of this site is reported as `page_not_found`. The answer is `202` when at least one page was queued, and `200` when none was. Read the progress from the pages.
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/read" \ -H "Content-Type: application/json" \ -d '{ "pageIds": [ "spg_01kvnwmagvf27rc9cze5rm9e1r" ], "generateAfter": true }'{ "data": { "accepted": [ "string" ], "skipped": [ { "pageId": "string", "reason": "string" } ], "started": true, "generateAfter": true }}Add pages
Judges a list of addresses and, unless `dryRun` is true, adds the accepted ones as pages and starts reading them in the background. The rules are the dashboard's: a path is resolved against the site's URL; a full address must be http or https and on the site's own origin (the origin of its URL or an allowed origin). An http address is upgraded to https, and a host that differs from an exactly allowed origin only by a leading `www.` is rewritten to it. The address is then normalized: the fragment, every `utm_` parameter, the click identifiers `gclid`, `gbraid`, `wbraid`, `dclid`, `fbclid`, `msclkid`, `ttclid`, `twclid`, `li_fat_id`, `igshid`, `yclid`, `srsltid`, `mc_cid`, `mc_eid`, `_ga`, `_gl` and `_kx`, and a trailing slash on a path other than `/` are removed; other query parameters are kept as written, in order. A repeat is ignored, and above 50 non-empty lines the whole request is refused with `invalid_request` and nothing is created. The answer names the outcome of every line. The answer is `202` when a read was started: read the progress from the pages. It is `200` for a dry run, and when no line was accepted.
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.