iAdvizeDocs

List a site's pages

Returns the pages of this site, newest first, with the site's totals by status and type and the generation budget for the current UTC day. The totals count every page whatever the filters. A list never carries the extracted text: get one page for it. 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}/pages

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

q?string

Only pages whose address or title contains this text, ignoring case.

Lengthlength <= 200
type?string

Only pages of this type.

Value in

  • "product"
  • "category"
  • "content"
  • "home"
  • "unknown"
status?string

Only pages with this status.

Value in

  • "pending"
  • "reading"
  • "read"
  • "failed"
  • "unsupported"
language?string

Only pages in this language.

Lengthlength <= 10
startersGenerated?boolean

true for pages that produced at least one question, false for pages that produced none.

lastGeneration?string

Only pages whose latest generation ended this way.

Value in

  • "written"
  • "none_passed"
  • "skipped"
  • "failed"
  • "read"
  • "unsupported"
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/pages"
{  "data": [    {      "id": "spg_01kvnwmagvf27rc9cze5rm9e1r",      "url": "https://shop.example/products/trail-shoe",      "finalUrl": null,      "source": "manual",      "pageType": "product",      "status": "read",      "reason": null,      "language": "en",      "title": "Trail shoe",      "lastReadAt": "2026-10-03T08:59:00.000Z",      "createdAt": "2026-10-03T08:58:00.000Z",      "updatedAt": "2026-10-03T08:59:00.000Z",      "starterQuestionCount": 3,      "lastGeneration": {        "id": "spgr_01kvnwmagvf27rc9cze5rm9e1r",        "trigger": "requested",        "outcome": "written",        "reason": null,        "catalogReason": null,        "catalogRecordTitle": "Trail shoe",        "catalogRecordId": "gid://shopify/Product/8123",        "candidates": 6,        "questionsWritten": 3,        "createdAt": "2026-10-03T09:00:00.000Z",        "finishedAt": "2026-10-03T09:00:12.000Z"      }    }  ],  "meta": {    "nextCursor": null,    "totals": {      "total": 1,      "byStatus": {        "pending": 0,        "reading": 0,        "read": 1,        "failed": 0,        "unsupported": 0      },      "byType": {        "product": 1,        "category": 0,        "content": 0,        "home": 0,        "unknown": 0      }    },    "generationBudget": {      "limit": 200,      "used": 3,      "remaining": 197,      "resetsAt": "2026-10-04T00:00:00.000Z"    }  }}

Change a version's status

Moves a version through its lifecycle. Only the `status` can change here: the instructions are immutable. Promoting a version to `champion` archives the agent's current champion automatically (at most one champion per agent).

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: an address must be https and on the site's own origin, it is normalized (fragment, `utm_` parameters and a trailing slash removed), 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.