Update widgets
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"items":[{"id":1,"is_active":true,"name":"example","folder_id":1,"notification_emails":["example"],"captcha":true,"email_quality_filter":true}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.getsitecontrol.com/v1/sites/1/widgets \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "id": 1, "is_active": true, "name": "example", "folder_id": 1, "notification_emails": [ "example" ], "captcha": true, "email_quality_filter": true } ] }'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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Up to 100 widgets, each id once
object
Widget id from List widgets
True: on the site; false: off. Needs the widgets.full right
The name in the admin; surrounding spaces are trimmed. Its link path stays
Folder id from list_folders with type widget; 0 is General
Where responses are e-mailed; [] turns the e-mails off. Replaces the list
ReCAPTCHA on form submits; turning it on needs a plan with it
Reject submits with disposable or untrusted e-mail addresses; turning it on needs a plan with it
{ "items": [ { "id": 1, "is_active": true, "name": "example", "folder_id": 1, "notification_emails": [ "example" ], "captcha": true, "email_quality_filter": true } ]}Responses
Section titled “Responses”object
Every item, in the order given
object
Position of the item in the request, from 0
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.
The fields that changed: is_active, name, folder, notification_emails, captcha, email_quality_filter, is_deleted
Why it failed; null unless result is failed
The widget after the call; null when it was not found
object
object
0 is General, where items outside any folder are
{ "items": [ { "result": "updated", "reason": "widget_not_found" } ]}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
forbidden: an item turns a widget on or off and the key lacks widgets.full; nothing is written
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
temporarily_unavailable: the plan could not be checked for reCAPTCHA or the e-mail quality filter; nothing is written
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds