---
title: "Preview a settings change"
method: POST
path: "/v1/projects/{projectId}/settings-changes/preview"
tags: ["Settings changes"]
---

# Preview a settings change

`POST /v1/projects/{projectId}/settings-changes/preview`

## Request

- Base URL: `https://hootlens-api-368877148687.us-east1.run.app`
- URL: `https://hootlens-api-368877148687.us-east1.run.app/v1/projects/{projectId}/settings-changes/preview`
- Auth: HTTP bearer

Computes what a change to page targeting, goals, funnels, privacy or per-path presets would do, without making it: the exact diff, effects read from the site's own data, warnings and a change token valid for 10 minutes. Owners may change every area; editors goals and funnels. A change that would make privacy looser (removing a mask or block selector, unmasking an input, keeping query strings, a less strict preset, removing or loosening a path preset) is refused with 403 and code privacy_weakening_refused. At most 30 a minute.

Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).

## Path parameters

- `projectId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.

## Request body

- SettingsPreview
  - `changes` object, required
    - `targeting` object
      - `addInclude` string[]
      - `removeInclude` string[]
      - `addExclude` string[]
      - `removeExclude` string[]
    - `goals` object
      - `add` union[]
        - union
          - object
            - `kind` 'click', required
            - `name` string, required
            - `by` 'selector', required
            - `match` string, required
          - object
            - `kind` 'click', required
            - `name` string, required
            - `by` 'hootId', required
            - `match` string, required
          - object
            - `kind` 'click', required
            - `name` string, required
            - `by` 'label', required
            - `match` string, required
          - object
            - `kind` 'page', required
            - `name` string, required
            - `match` string, required
      - `update` union[]
        - union
          - object
            - `id` string, required
            - `kind` 'click', required
            - `name` string, required
            - `by` 'selector', required
            - `match` string, required
          - object
            - `id` string, required
            - `kind` 'click', required
            - `name` string, required
            - `by` 'hootId', required
            - `match` string, required
          - object
            - `id` string, required
            - `kind` 'click', required
            - `name` string, required
            - `by` 'label', required
            - `match` string, required
          - object
            - `id` string, required
            - `kind` 'page', required
            - `name` string, required
            - `match` string, required
      - `remove` string[]
    - `funnels` object
      - `add` object[]
        - `name` string, required
        - `steps` string[], required
      - `remove` string[]
    - `privacy` object
      - `preset` 'full' | 'balanced' | 'strict'
      - `addMaskTextSelectors` string[]
      - `addBlockSelectors` string[]
      - `removeUnmaskInputSelectors` string[]
      - `captureQueryStrings` boolean
    - `pathPresets` object
      - `set` object[]
        - `match` string, required
        - `preset` 'safe-form' | 'balanced' | 'strict', required

## Response `200`

The preview. changed is false, with no token, when the site already has these settings.

- SettingsPreviewResult
  - `changed` boolean, required
  - `token` string: Pass to apply. Absent when nothing would change.
  - `expiresAt` integer: Epoch milliseconds.
  - `expiresInSeconds` integer
  - `diff` object[], required
    - `area` 'targeting' | 'goals' | 'funnels' | 'privacy' | 'pathPresets', required
    - `action` 'add' | 'remove' | 'change', required
    - `summary` string, required
  - `effects` string[], required
  - `warnings` string[], required
  - `message` string
  - `next` string

## Other responses

- `400`: The request fields are invalid.
- `401`: The credential is missing, expired or revoked.
- `403`: The credential or the person's permissions on the site do not permit this action.
- `404`: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
- `429`: A rate limit or a per-site limit was reached.

---

[API](https://skmtc.dev/hootlens/apis/hoot-lens-api.md) · [All operations](https://skmtc.dev/hootlens/apis/hoot-lens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hootlens/apis/hoot-lens-api/revisions/f64f8dc7b84e?raw)