Add a widget to an A/B test
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/1/ab-test';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"1"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.getsitecontrol.com/v1/sites/1/widgets/1/ab-test \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "1" }'Puts the widget into the named test, starting the test when the slot is empty, or moves it from another test; its results count from now. A widget already in that test is returned with changed: false. The widget keeps its on/off state.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Widget id from List widgets
Widget id from List widgets
Header Parameters
Section titled “Header Parameters”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.
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 Bodyrequired
Section titled “Request Bodyrequired”object
One of the five slots; a slot not in use starts a new test
Responses
Section titled “Responses”object
object
The widget’s first headline, plain text; null when it has none
Where the widget sits on the page, named as in the admin. modal: a window centred over the page. bar: a strip across the top or bottom of the page. panel: a box attached to the bottom of the screen, opened from its header. slide_in: a box that slides in from a corner. sidebar: a panel attached to the left or right edge of the screen. fullscreen: covers the whole screen. inline: placed inside the page content. other: a layout the admin no longer offers. “Pop-up” is not a layout: users call any widget a pop-up.
object
object
0 is General, where items outside any folder are
Event types the widget can produce besides show and close
object
Has an e-mail field
Has a phone field
A button copies or applies a discount code
Has a game: a wheel, a scratch card or a reveal
Has a countdown timer
Has a teaser, the small tab shown before or after it
ReCAPTCHA checks its form submits
A new subscriber confirms the address by e-mail first
Submits with disposable or untrusted e-mail addresses are rejected
Responses are e-mailed: switched on, with a recipient
In an A/B test, named in ab_test_group
An integration, webhook or Zapier switched on sends its responses
You have a draft of it with unsaved changes, see draft
object
False when some rules could not be read into the blocks below
Informational notes; wording is not stable, do not parse
Null when the block could not be read
object
object
All: every item must hold; any: one is enough.
object
All: every item must hold; any: one is enough.
object
How a condition tests its value; any_of and none_of take a list, during and not_during a range, has_any_value and is_undefined no value.
object
Immediate: on page load; programmatically: only when the site’s code
shows it; triggers: when one of triggers fires.
object
What fires a show or a hide; a *_seconds or *_percent trigger carries its threshold in value.
object
object
What fires a show or a hide; a *_seconds or *_percent trigger carries its threshold in value.
object
object
The visitor’s event after which the widget stops showing; close and show are named for their event. action: after the visitor submits it or clicks its button. hide: after a hide trigger hides it. show_count: after count shows.
object
All: every item must hold; any: one is enough.
object
All: every item must hold; any: one is enough.
object
Date: a range of days; time: a range of hours in a time zone; weekday: days of the week, 0 is Sunday.
How a condition tests its value; any_of and none_of take a list, during and not_during a range, has_any_value and is_undefined no value.
object
object
Your draft of this widget while it has unsaved changes; null when it has none
object
New: started with create_widget_draft and not saved yet; the widget exists only in this draft. draft: your unsaved changes over the saved widget. synced: the draft matches the saved widget.
The draft’s revision: 1 when it started, one more per change; null when you have no draft of this widget
True: the widget was saved after your draft started, and saving would replace that save
Who made that save, when saved_changed; e-mail or name
When they saved, when saved_changed
When this draft started; a draft that started before this conversation is unfinished work, maybe yours
Last change to the draft
One permanent page per widget: your draft while it has unsaved changes, the saved widget otherwise, refreshed as you edit; null where live previews are not set up
Informational notes about the widget itself; wording is not stable, do not parse
Last change of the widget itself; a move to another folder does not change it
Last change made in the editor
Parts shortened in the list, as paths; the card has them whole. Empty when nothing was cut
False when the widget already was in the requested state
{ "widget": { "layout": "modal", "targeting": { "audience": { "match": "all", "segments": [ { "match": "all", "conditions": [ { "operator": "is" } ] } ] }, "start": { "mode": "immediate", "triggers": [ { "type": "exit_intent" } ] }, "hide": { "triggers": [ { "type": "exit_intent" } ] }, "stop": { "rules": [ { "event": "action", "mode": "forever" } ] }, "schedule": { "match": "all", "segments": [ { "match": "all", "conditions": [ { "key": "date", "operator": "is" } ] } ] } }, "draft": { "state": "new" }, "truncated": [] }}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
True when the response is a stored one, replayed
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
feature_unavailable: the site’s plan does not include A/B tests
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
widget_not_found: the site has no such widget, or it was deleted
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
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