Skip to content
Cloudflare API
Start here
API Reference

Turnstile

TurnstileWidgets

List Turnstile Widgets
GET/accounts/{account_id}/challenges/widgets
Turnstile Widget Details
GET/accounts/{account_id}/challenges/widgets/{sitekey}
Create a Turnstile Widget
POST/accounts/{account_id}/challenges/widgets
Update a Turnstile Widget
PUT/accounts/{account_id}/challenges/widgets/{sitekey}
Delete a Turnstile Widget
DELETE/accounts/{account_id}/challenges/widgets/{sitekey}
Rotate Secret for a Turnstile Widget
POST/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret
ModelsExpand Collapse
Widget object { bot_fight_mode, clearance_level, created_on, 11 more }

A Turnstile widget’s detailed configuration

bot_fight_mode: boolean

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

clearance_level: "no_clearance" or "jschallenge" or "managed" or "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: string

When the widget was created.

formatdate-time
domains: array of WidgetDomain
maxLength10
ephemeral_id: boolean

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

mode: "non-interactive" or "invisible" or "managed"

Widget Mode

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

When the widget was modified.

formatdate-time
name: string

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: boolean

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

region: "world" or "china"

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

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

Secret key for this widget.

sitekey: string

Widget item identifier tag.

maxLength32
deployed_via: optional "wrangler" or "dashboard" or "spin" or 2 more

Origin that created this widget, recorded at creation time and immutable afterward. Server-derived from the create request; not client-settable. Omitted from the response for widgets created before this field existed.

One of the following:
"wrangler"
"dashboard"
"spin"
"api"
"unknown"
last_modified_via: optional "wrangler" or "dashboard" or "spin" or 2 more

Origin of the most recent mutation (create, update, delete, or secret rotation). Server-derived; not client-settable. Omitted for widgets last mutated before this field existed.

One of the following:
"wrangler"
"dashboard"
"spin"
"api"
"unknown"
WidgetDomain = string

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

WidgetListResponse object { bot_fight_mode, clearance_level, created_on, 10 more }

A Turnstile Widgets configuration as it appears in listings

bot_fight_mode: boolean

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

clearance_level: "no_clearance" or "jschallenge" or "managed" or "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: string

When the widget was created.

formatdate-time
domains: array of WidgetDomain
maxLength10
ephemeral_id: boolean

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

mode: "non-interactive" or "invisible" or "managed"

Widget Mode

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

When the widget was modified.

formatdate-time
name: string

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: boolean

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

region: "world" or "china"

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

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

Widget item identifier tag.

maxLength32
deployed_via: optional "wrangler" or "dashboard" or "spin" or 2 more

Origin that created this widget, recorded at creation time and immutable afterward. Server-derived from the create request; not client-settable. Omitted from the response for widgets created before this field existed.

One of the following:
"wrangler"
"dashboard"
"spin"
"api"
"unknown"
last_modified_via: optional "wrangler" or "dashboard" or "spin" or 2 more

Origin of the most recent mutation (create, update, delete, or secret rotation). Server-derived; not client-settable. Omitted for widgets last mutated before this field existed.

One of the following:
"wrangler"
"dashboard"
"spin"
"api"
"unknown"