---
title: "Update widgets"
method: PATCH
path: "/v1/sites/{site_id}/widgets"
tags: ["Widgets"]
---

# Update widgets

`PATCH /v1/sites/{site_id}/widgets`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/widgets`
- Auth: HTTP bearer

Changes the named widgets at once: on or off, name, folder, the e-mails
responses go to, reCAPTCHA and the e-mail quality filter. Each item names a
widget by id and the fields to set; a field left out is kept. Up to 100 items
per call, the page size of List widgets: select with List widgets, then send
the ids.

The answer reports every item in the order given: `updated`, `unchanged`
(already in that state, nothing written) or `failed` with a `reason`; one
failed item changes nothing of its own and does not stop the others. Items
with `is_active` need the widgets.full right; without it the whole call is
refused and nothing is written.

One widget is a list of one. The content (pages, texts, targeting, look) is
changed with the widget tools; this operation never touches it or your
draft. A move to another folder does not change `updated_at`.

## Path parameters

- `site_id` integer, required

## Request body

- WidgetsUpdate
  - `items` WidgetUpdateItem[], required: Up to 100 widgets, each id once
    - `id` integer, required: Widget id from List widgets
    - `is_active` boolean, nullable: true: on the site; false: off. Needs the widgets.full right
    - `name` string, nullable: The name in the admin; surrounding spaces are trimmed. Its link path stays
    - `folder_id` integer, nullable: Folder id from `list_folders` with type widget; 0 is General
    - `notification_emails` string[], nullable: Where responses are e-mailed; [] turns the e-mails off. Replaces the list
    - `captcha` boolean, nullable: reCAPTCHA on form submits; turning it on needs a plan with it
    - `email_quality_filter` boolean, nullable: Reject submits with disposable or untrusted e-mail addresses; turning it on needs a plan with it

## Response `200`

Successful Response

- WidgetsBatch
  - `items` WidgetBatchItem[], required: Every item, in the order given
    - `index` integer, required: Position of the item in the request, from 0
    - `id` integer, required
    - `result` 'updated' | 'unchanged' | 'failed', required: updated: the change was written. unchanged: the widget already was in that state, nothing was written. failed: nothing of this item was written, see `reason`.
    - `changed` string[], required: The fields that changed: is_active, name, folder, notification_emails, captcha, email_quality_filter, is_deleted
    - `reason` 'widget_not_found' | 'folder_not_found' | 'account_suspended' | 'feature_unavailable': widget_not_found: no widget of the site has this id; a deleted one is found only by Restore widgets. folder_not_found: no folder of the site's widgets has this id; use `list_folders` with type widget, 0 is General. account_suspended: the site is suspended, a widget cannot be turned on. feature_unavailable: the site's plan does not include this setting, see `detail`.
    - `detail` string, nullable
    - `widget` WidgetRef
      - `id` integer, required
      - `name` string, nullable
      - `is_active` boolean, required
      - `folder` Folder, required
        - `id` integer, required: 0 is General, where items outside any folder are
        - `name` string, required
  - `updated` integer, required
  - `unchanged` integer, required
  - `failed` integer, required

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: `forbidden`: an item turns a widget on or off and the key lacks widgets.full; nothing is written
- `404`: Not found
- `409`: Conflict
- `413`: Request body too large
- `422`: Validation failed
- `429`: Rate limited
- `503`: `temporarily_unavailable`: the plan could not be checked for reCAPTCHA or the e-mail quality filter; nothing is written

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)