---
title: "Change a site"
method: PATCH
path: "/v1/sites/{siteId}"
tags: ["Sites"]
---

# Change a site

`PATCH /v1/sites/{siteId}`

## Request

- Base URL: `https://api.ironfang.com/analytics`
- URL: `https://api.ironfang.com/analytics/v1/sites/{siteId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Changes a site, made against the version you read: if the site has changed since, the request is refused with 409 `version_conflict` and nothing is applied. `config` merges onto the configuration in force: a field left out keeps its value and a list that is named replaces the whole list. A configuration that differs from the one in force becomes a new immutable version. Setting `status` to `disabled` stops collection without deleting anything. Needs analytics.sites.write.

## Request body

- object
  - `config` SiteConfig: What the site's recorder may capture. Whatever this says, anything that looks like a payment card number (13 to 19 digits passing the Luhn check) is masked wherever it appears, and card, CVV, password and one-time-code fields are blocked.
    - `analytics` object: Session analytics, from SDK 0.6.0. Sessions are the root: a recording belongs to its session, so a site records only while it follows sessions, and may follow sessions without recording. The site's consent mode and excluded addresses apply as they do to recording.
      - `console_errors` boolean: Add console.error calls to sessions (SDK 0.7.0), their arguments serialised safely and scrubbed as error messages are. A version stored before this switch reads as false.
      - `enabled` boolean: Report every eligible visitor's pages from page load, recorded or not. Must be true while recording.enabled is (422 otherwise). A version stored before this rule that records reads as true.
      - `errors` boolean: Add uncaught errors and unhandled rejections to sessions.
      - `request_sample_percent` integer: The share of successful requests kept, decided per request in the browser. Failures are never sampled. A session says the share it was kept at, and how many were left out.
      - `requests` boolean: Add requests that fail (an answer of 400 or above, no answer, a timeout, a resource that did not load), that the page aborted, or that take 5 seconds or longer, to sessions.
      - `successful_requests` boolean: Add the rest, quick successes, to sessions too (SDK 0.7.0). A version stored before this switch reads as false.
    - `recording` object
      - `allowed_query_parameters` string[]: Query parameters whose values are kept in recorded URLs while record_all_query_parameters is off; all others are removed.
      - `block_selectors` string[]
      - `checkpoint_interval_seconds` integer
      - `consent` 'opt_out' | 'required': opt_out records from page load unless the page opts the visitor out with setConsent({replay: false}), which the browser remembers. required records nothing until the page grants replay consent; the site's snippet then carries data-consent="required" so nothing is requested before it.
      - `enabled` boolean
      - `excluded_ip_ranges` string[]: Visitor addresses that are never recorded, such as the site owner's own networks: public IPv4 or IPv6 addresses, or CIDR ranges such as 203.0.113.0/24 or 2001:db8:1:2::/64. A visitor inside one is refused at admission, and a recording already open from there does not continue. The list is not sent to pages; the collector's GET /v1/address tells a browser its own address and the range to add for it.
      - `mask_inputs` boolean: Mask every form field's value and text typed into an editable region.
      - `mask_selectors` string[]
      - `mask_text` boolean: Mask every text node; unmask_selectors then expose reviewed static text.
      - `max_compressed_mib` integer
      - `max_duration_minutes` integer
      - `record_all_query_parameters` boolean: Keep every query value in recorded URLs except those in removed_query_parameters. Off, only allowed_query_parameters keep theirs. Fragments are removed either way. Needs SDK 0.2.1 or later; older recorders keep only the allowed parameters.
      - `removed_query_parameters` string[]: Query parameters whose values are removed while record_all_query_parameters is on, such as a token or an email address.
      - `sample_rate_percent` integer
      - `unmask_selectors` string[]
  - `name` string
  - `retention_days` integer: Raising it above session_retention_days raises that too.
  - `session_retention_days` integer: At least retention_days.
  - `status` 'active' | 'disabled'
  - `timezone` string
  - `version` integer, required: The site version the change was made against.

## Response `200`

The site after the change

- SiteDetail
  - `config` ConfigVersion, required
    - `config` SiteConfig, required: What the site's recorder may capture. Whatever this says, anything that looks like a payment card number (13 to 19 digits passing the Luhn check) is masked wherever it appears, and card, CVV, password and one-time-code fields are blocked.
      - `analytics` object: Session analytics, from SDK 0.6.0. Sessions are the root: a recording belongs to its session, so a site records only while it follows sessions, and may follow sessions without recording. The site's consent mode and excluded addresses apply as they do to recording.
        - `console_errors` boolean: Add console.error calls to sessions (SDK 0.7.0), their arguments serialised safely and scrubbed as error messages are. A version stored before this switch reads as false.
        - `enabled` boolean: Report every eligible visitor's pages from page load, recorded or not. Must be true while recording.enabled is (422 otherwise). A version stored before this rule that records reads as true.
        - `errors` boolean: Add uncaught errors and unhandled rejections to sessions.
        - `request_sample_percent` integer: The share of successful requests kept, decided per request in the browser. Failures are never sampled. A session says the share it was kept at, and how many were left out.
        - `requests` boolean: Add requests that fail (an answer of 400 or above, no answer, a timeout, a resource that did not load), that the page aborted, or that take 5 seconds or longer, to sessions.
        - `successful_requests` boolean: Add the rest, quick successes, to sessions too (SDK 0.7.0). A version stored before this switch reads as false.
      - `recording` object
        - `allowed_query_parameters` string[]: Query parameters whose values are kept in recorded URLs while record_all_query_parameters is off; all others are removed.
        - `block_selectors` string[]
        - `checkpoint_interval_seconds` integer
        - `consent` 'opt_out' | 'required': opt_out records from page load unless the page opts the visitor out with setConsent({replay: false}), which the browser remembers. required records nothing until the page grants replay consent; the site's snippet then carries data-consent="required" so nothing is requested before it.
        - `enabled` boolean
        - `excluded_ip_ranges` string[]: Visitor addresses that are never recorded, such as the site owner's own networks: public IPv4 or IPv6 addresses, or CIDR ranges such as 203.0.113.0/24 or 2001:db8:1:2::/64. A visitor inside one is refused at admission, and a recording already open from there does not continue. The list is not sent to pages; the collector's GET /v1/address tells a browser its own address and the range to add for it.
        - `mask_inputs` boolean: Mask every form field's value and text typed into an editable region.
        - `mask_selectors` string[]
        - `mask_text` boolean: Mask every text node; unmask_selectors then expose reviewed static text.
        - `max_compressed_mib` integer
        - `max_duration_minutes` integer
        - `record_all_query_parameters` boolean: Keep every query value in recorded URLs except those in removed_query_parameters. Off, only allowed_query_parameters keep theirs. Fragments are removed either way. Needs SDK 0.2.1 or later; older recorders keep only the allowed parameters.
        - `removed_query_parameters` string[]: Query parameters whose values are removed while record_all_query_parameters is on, such as a token or an email address.
        - `sample_rate_percent` integer
        - `unmask_selectors` string[]
    - `created_at` string, date-time, required
    - `created_by` string, required: The user id, or key:<id> for a platform key.
    - `id` string, uuid, required
    - `sha256` string, required: SHA-256 of the stored configuration document.
    - `site_id` string, uuid, required
    - `version` integer, required
  - `keys` SiteKey[], required: The keys currently accepted, newest first.
    - `created_at` string, date-time, required
    - `id` string, uuid, required
    - `key` string, required: Public collection key; safe to publish.
    - `retires_at` string, date-time
    - `site_id` string, uuid, required
    - `state` 'active' | 'retiring', required
  - `origins` Origin[], required
    - `checked_at` string, date-time
    - `created_at` string, date-time, required
    - `dns_record` object: The TXT record to publish; absent for loopback origins.
      - `name` string, required
      - `type` 'TXT', required
      - `value` string, required
    - `id` string, uuid, required
    - `origin` string, required
    - `site_id` string, uuid, required
    - `verification` 'pending' | 'verified' | 'not_required', required
    - `verification_token` string
    - `verified_at` string, date-time
  - `site` Site, required
    - `config_version` integer, required: The configuration version in force.
    - `created_at` string, date-time, required
    - `disabled_at` string, date-time
    - `external_id` string, nullable, required: Your own identifier for the site, when one was given at creation.
    - `id` string, uuid, required
    - `name` string, required
    - `organisation_id` string, uuid, required
    - `retention_days` integer, required: Days a recording is kept.
    - `session_retention_days` integer, required: Days session history is kept, never fewer than retention_days. A session loses its IP address, user agent and visitor id after retention_days.
    - `status` 'active' | 'disabled', required
    - `timezone` string, required
    - `updated_at` string, date-time, required
    - `version` integer, required: Name this in a PATCH.

## Other responses

- `400`: The body is not one strict JSON value of the documented shape (`invalid_json`).
- `401`: No credential, an invalid one, an expired partner integration key, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `api_key_expired`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, names another organisation, or belongs to a partner integration that is not active (`forbidden`, `insufficient_scope`, `integration_inactive`).
- `404`: No such object in this organisation (`not_found`).
- `409`: The object already exists (`conflict`), or the site changed since it was read (`version_conflict`).
- `422`: A field is invalid, or a limit would be exceeded; the message names it (`invalid_request`, `limit_reached`).

---

[API](https://skmtc.dev/ironfang/apis/ironfang-analytics-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/revisions/08197080c3d7?raw)