Skip to main content

​
Overview

The Site Optimization API surfaces the work Scrunch recommends for a brand’s pages, and the optimization runs behind them. It answers two questions:
  • What should we fix first? Recommendations grouped by type — one row per best practice — with the projected site-score lift for resolving each type.
  • What’s open on this page? Recommendations by page, with each page’s AI-visibility scores, its open recommendations, and what it already does well — plus the block-by-block optimization run Scrunch generated for it.

​
Endpoints

All require a bearer token. The apply endpoint requires the optimize scope; the reads require query. See Authentication.

​
Example requests

Rank the work by type, then open one type:
Read one page’s recommendations, or open its optimization run:

​
Reading the fields

site_impact_pp is percentage points of site score, not a percentage change. A value of 2.4 means resolving that whole type is projected to move the site score by 2.4 points, not to improve it by 2.4%. Header counts and the page window are scoped differently. On the by-type detail endpoint, the per-state counts in the header describe the entire type across the brand. The pages array beneath them is one paginated window, filtered by state and sized by limit/offset. They will not match, and that is intended — don’t compute a total by counting the array. state accepts all, pending, reviewed, staged, and deployed, and filters only the page window.
path is required on the optimization endpoint. Calling GET /site-optimization/optimization without it returns 422, not an empty result — there is no “all pages” form of that request. The by-page list is the opposite: path is optional there, and omitting it pages through every audited path.
Apply records a decision; it does not publish anything. POST /optimization/apply is for changes made outside Scrunch — in your CMS, say — so that a run which will never go through Scrunch review is not left looking outstanding. It writes the acknowledgement and returns the run; it does not deploy, and it does not edit your site. Send exactly one of approve_all: true or a reviews list of per-block verdicts keyed by chunk id. Only reviewed runs come back by default. The optimization endpoint returns runs a human accepted — completed, staged, deployed, acknowledged — and hides raw unreviewed output. Pass status explicitly if you need to see a run that nobody has looked at yet.
For a brand using Site Optimization’s page selection, by-type counts and lift cover the enabled pages only. Two brands with identical sites can therefore report different totals.
Paths are matched exactly, including the leading slash. ?path=/about and ?path=about are not the same request, and the second matches nothing.