---
title: "Delete widgets"
method: POST
path: "/v1/sites/{site_id}/widgets/delete"
tags: ["Widgets"]
---

# Delete widgets

`POST /v1/sites/{site_id}/widgets/delete`

## Request

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

Puts the named widgets in the trash: they leave the site at once and keep
their responses, statistics, integrations and history; Restore widgets brings
them back whole. A widget that is on is deleted as it is; its item says
`is_active: true`, so tell the user it was live. A widget in an A/B test
leaves the test. Up to 100 ids per call; the answer reports every one, a
widget already deleted as `unchanged`. Deleted widgets are listed with
`list_widgets(is_deleted=true)`.

## Path parameters

- `site_id` integer, required

## Headers

- `Idempotency-Key` string: Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with `Idempotency-Replayed: true` instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.

## Request body

- WidgetIds
  - `ids` integer[], required: Widget ids from List widgets, up to 100, each once

## 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`: Access denied
- `404`: Not found
- `409`: Conflict
- `413`: Request body too large
- `422`: Validation failed
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

[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)