Skip to content
Cloudflare API
Start here
API Reference
Turnstile

Widgets

List Turnstile Widgets
turnstile.widgets.list(WidgetListParams**kwargs) -> SyncV4PagePaginationArray[WidgetListResponse]
GET/accounts/{account_id}/challenges/widgets
Turnstile Widget Details
turnstile.widgets.get(strsitekey, WidgetGetParams**kwargs) -> Widget
GET/accounts/{account_id}/challenges/widgets/{sitekey}
Create a Turnstile Widget
turnstile.widgets.create(WidgetCreateParams**kwargs) -> Widget
POST/accounts/{account_id}/challenges/widgets
Update a Turnstile Widget
turnstile.widgets.update(strsitekey, WidgetUpdateParams**kwargs) -> Widget
PUT/accounts/{account_id}/challenges/widgets/{sitekey}
Delete a Turnstile Widget
turnstile.widgets.delete(strsitekey, WidgetDeleteParams**kwargs) -> Widget
DELETE/accounts/{account_id}/challenges/widgets/{sitekey}
Rotate Secret for a Turnstile Widget
turnstile.widgets.rotate_secret(strsitekey, WidgetRotateSecretParams**kwargs) -> Widget
POST/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret
ModelsExpand Collapse
class Widget: …

A Turnstile widget's detailed configuration

bot_fight_mode: bool

If bot_fight_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).

clearance_level: Literal["no_clearance", "jschallenge", "managed", "interactive"]

If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set

One of the following:
"no_clearance"
"jschallenge"
"managed"
"interactive"
created_on: datetime

When the widget was created.

formatdate-time
domains: List[WidgetDomain]
maxLength10
ephemeral_id: bool

Return the Ephemeral ID in /siteverify (ENT only).

mode: Literal["non-interactive", "invisible", "managed"]

Widget Mode

One of the following:
"non-interactive"
"invisible"
"managed"
modified_on: datetime

When the widget was modified.

formatdate-time
name: str

Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used.

maxLength254
minLength1
offlabel: bool

Do not show any Cloudflare branding on the widget (ENT only).

region: Literal["world", "china"]

Region where this widget can be used. This cannot be changed after creation.

One of the following:
"world"
"china"
secret: str

Secret key for this widget.

sitekey: str

Widget item identifier tag.

maxLength32
str

Hosts as a hostname or IPv4/IPv6 address represented by strings. The widget will only work on these domains, and their subdomains.

class WidgetListResponse: …

A Turnstile Widgets configuration as it appears in listings

bot_fight_mode: bool

If bot_fight_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).

clearance_level: Literal["no_clearance", "jschallenge", "managed", "interactive"]

If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set

One of the following:
"no_clearance"
"jschallenge"
"managed"
"interactive"
created_on: datetime

When the widget was created.

formatdate-time
domains: List[WidgetDomain]
maxLength10
ephemeral_id: bool

Return the Ephemeral ID in /siteverify (ENT only).

mode: Literal["non-interactive", "invisible", "managed"]

Widget Mode

One of the following:
"non-interactive"
"invisible"
"managed"
modified_on: datetime

When the widget was modified.

formatdate-time
name: str

Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used.

maxLength254
minLength1
offlabel: bool

Do not show any Cloudflare branding on the widget (ENT only).

region: Literal["world", "china"]

Region where this widget can be used. This cannot be changed after creation.

One of the following:
"world"
"china"
sitekey: str

Widget item identifier tag.

maxLength32