> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Site Optimization API: Recommendations, by type and by page

> List a brand's optimization recommendations grouped by best practice or per page, with projected site-score lift, plus the optimization run behind any one page.

## 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

| Method | Path                                                                       | Purpose                                                               |
| ------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| GET    | `/{brand_id}/site-optimization/recommendations/by-type`                    | Every recommendation type, with projected lift and page counts.       |
| GET    | `/{brand_id}/site-optimization/recommendations/by-type/{best_practice_id}` | One type's detail, plus a paginated window of its affected pages.     |
| GET    | `/{brand_id}/site-optimization/recommendations/by-page`                    | Latest recommendations per page, optionally scoped to specific paths. |
| GET    | `/{brand_id}/site-optimization/optimization`                               | The latest optimization run for one page.                             |
| POST   | `/{brand_id}/site-optimization/optimization/apply`                         | Record that a run was acted on outside Scrunch.                       |

All require a bearer token. The apply endpoint requires the `optimize` scope; the reads require `query`. See [Authentication](/getting-started/authentication).

***

## Example requests

Rank the work by type, then open one type:

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-type"
```

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-type/heading-structure?state=pending&limit=50"
```

Read one page's recommendations, or open its optimization run:

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-page?path=/about&path=/pricing"
```

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/site-optimization/optimization?path=/pricing"
```

***

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

<Warning>
  **`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.
</Warning>

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

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

<Note>
  Paths are matched exactly, including the leading slash. `?path=/about` and `?path=about` are not the same request, and the second matches nothing.
</Note>


## Related topics

- [List Recommendation Types](/api-reference/site-optimization/list-recommendation-types.md)
- [List Page Recommendations](/api-reference/site-optimization/list-page-recommendations.md)
- [Get Recommendation Type Detail](/api-reference/site-optimization/get-recommendation-type-detail.md)