Cloudflare Turnstile is a CAPTCHA replacement that verifies visitors without showing a challenge. The API provides a widget for client-side integration and a server-side siteverify endpoint for token validation, with support for managed, non-interactive, and invisible modes.
openapi: 3.1.0
info:
title: Cloudflare Turnstile API
description: >-
Cloudflare Turnstile is a CAPTCHA replacement that verifies visitors
without showing a challenge. The API provides a server-side siteverify
endpoint for token validation and management endpoints for creating and
configuring Turnstile widgets with support for managed, non-interactive,
and invisible modes.
version: '4.0'
contact:
name: Cloudflare Support
url: https://support.cloudflare.com/
termsOfService: https://www.cloudflare.com/terms/
externalDocs:
description: Cloudflare Turnstile Documentation
url: https://developers.cloudflare.com/turnstile/
servers:
- url: https://api.cloudflare.com/client/v4
description: Cloudflare API v4 Production Server
tags:
- name: Verification
description: >-
Verify Turnstile challenge tokens on the server side.
- name: Widgets
description: >-
Create, list, update, and delete Turnstile widget configurations.
security:
- bearerAuth: []
paths:
/accounts/{account_id}/challenges/widgets:
get:
operationId: listTurnstileWidgets
summary: Cloudflare List Turnstile Widgets
description: >-
Returns all Turnstile widget configurations for the account.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: List of widgets.
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetListResponse'
examples:
Listturnstilewidgets200Example:
summary: Default listTurnstileWidgets 200 response
x-microcks-default: true
value:
result:
- sitekey: example_value
secret: example_value
name: Example Title
domains: {}
mode: managed
bot_fight_mode: true
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
success: true
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createTurnstileWidget
summary: Cloudflare Create Turnstile Widget
description: >-
Create a new Turnstile widget with the specified mode and allowed
domains.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetInput'
examples:
CreateturnstilewidgetRequestExample:
summary: Default createTurnstileWidget request
x-microcks-default: true
value:
name: Example Title
domains:
- example_value
mode: managed
bot_fight_mode: true
responses:
'200':
description: Widget created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetResponse'
examples:
Createturnstilewidget200Example:
summary: Default createTurnstileWidget 200 response
x-microcks-default: true
value:
result:
sitekey: example_value
secret: example_value
name: Example Title
domains:
- {}
mode: managed
bot_fight_mode: true
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
success: true
errors:
- {}
messages:
- {}
'400':
description: Bad request.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/challenges/widgets/{sitekey}:
get:
operationId: getTurnstileWidget
summary: Cloudflare Get Turnstile Widget
description: >-
Retrieve details of a specific Turnstile widget.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/Sitekey'
responses:
'200':
description: Widget details.
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetResponse'
examples:
Getturnstilewidget200Example:
summary: Default getTurnstileWidget 200 response
x-microcks-default: true
value:
result:
sitekey: example_value
secret: example_value
name: Example Title
domains:
- {}
mode: managed
bot_fight_mode: true
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
success: true
errors:
- {}
messages:
- {}
'401':
description: Unauthorized.
'404':
description: Widget not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateTurnstileWidget
summary: Cloudflare Update Turnstile Widget
description: >-
Update the configuration of a Turnstile widget.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/Sitekey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetInput'
examples:
UpdateturnstilewidgetRequestExample:
summary: Default updateTurnstileWidget request
x-microcks-default: true
value:
name: Example Title
domains:
- example_value
mode: managed
bot_fight_mode: true
responses:
'200':
description: Widget updated successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteTurnstileWidget
summary: Cloudflare Delete Turnstile Widget
description: >-
Delete a Turnstile widget configuration.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/Sitekey'
responses:
'200':
description: Widget deleted.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret:
post:
operationId: rotateTurnstileSecret
summary: Cloudflare Rotate Widget Secret
description: >-
Rotate the secret key for a Turnstile widget. The previous secret
remains valid for a transition period.
tags:
- Widgets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/Sitekey'
responses:
'200':
description: Secret rotated successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/siteverify:
post:
operationId: verifyTurnstileToken
summary: Cloudflare Verify Turnstile Token
description: >-
Validate a Turnstile challenge token on the server side. This is the
primary endpoint for verifying that a user has passed the Turnstile
challenge.
tags:
- Verification
security: []
servers:
- url: https://challenges.cloudflare.com
description: Turnstile Verification Server
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- secret
- response
properties:
secret:
type: string
description: The widget's secret key.
response:
type: string
description: The Turnstile token from the client.
remoteip:
type: string
description: The user's IP address.
examples:
VerifyturnstiletokenRequestExample:
summary: Default verifyTurnstileToken request
x-microcks-default: true
value:
secret: example_value
response: example_value
remoteip: example_value
responses:
'200':
description: Verification result.
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyResponse'
examples:
Verifyturnstiletoken200Example:
summary: Default verifyTurnstileToken 200 response
x-microcks-default: true
value:
success: true
challenge_ts: '2026-01-15T10:30:00Z'
hostname: example_value
error-codes:
- example_value
action: example_value
cdata: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API token with Turnstile permissions.
parameters:
AccountId:
name: account_id
in: path
required: true
description: The unique identifier of the Cloudflare account.
schema:
type: string
Sitekey:
name: sitekey
in: path
required: true
description: The site key of the Turnstile widget.
schema:
type: string
schemas:
Widget:
type: object
properties:
sitekey:
type: string
description: The public site key for the widget.
example: example_value
secret:
type: string
description: The secret key for server-side verification.
example: example_value
name:
type: string
description: A human-readable name for the widget.
example: Example Title
domains:
type: array
items:
type: string
description: Allowed domains for the widget.
example: []
mode:
type: string
enum:
- managed
- non-interactive
- invisible
description: The challenge mode for the widget.
example: managed
bot_fight_mode:
type: boolean
description: Whether Bot Fight Mode is enabled.
example: true
created_on:
type: string
format: date-time
example: '2026-01-15T10:30:00Z'
modified_on:
type: string
format: date-time
example: '2026-01-15T10:30:00Z'
WidgetInput:
type: object
required:
- name
- domains
- mode
properties:
name:
type: string
description: Name for the widget.
example: Example Title
domains:
type: array
items:
type: string
description: Allowed domains.
example: []
mode:
type: string
enum:
- managed
- non-interactive
- invisible
example: managed
bot_fight_mode:
type: boolean
example: true
WidgetResponse:
type: object
properties:
result:
$ref: '#/components/schemas/Widget'
success:
type: boolean
example: true
errors:
type: array
items:
type: object
example: []
messages:
type: array
items:
type: object
example: []
WidgetListResponse:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Widget'
example: []
success:
type: boolean
example: true
VerifyResponse:
type: object
properties:
success:
type: boolean
description: Whether the token was valid.
example: true
challenge_ts:
type: string
format: date-time
description: Timestamp of the challenge.
example: '2026-01-15T10:30:00Z'
hostname:
type: string
description: Hostname for which the challenge was solved.
example: example_value
error-codes:
type: array
items:
type: string
description: Error codes if verification failed.
example: []
action:
type: string
description: The action name from the widget.
example: example_value
cdata:
type: string
description: Custom data from the widget.
example: example_value