1# API Reference
2 
3## Client-Side JavaScript API
4 
5The Turnstile JavaScript API is available at `window.turnstile` after loading the script.
6 
7### `turnstile.render(container, options)`
8 
9Renders a Turnstile widget into a container element.
10 
11**Parameters:**
12- `container` (string | HTMLElement): CSS selector or DOM element
13- `options` (TurnstileOptions): Configuration object (see [configuration.md](configuration.md))
14 
15**Returns:** `string` - Widget ID for use with other API methods
16 
17**Example:**
18```javascript
19const widgetId = window.turnstile.render('#my-container', {
20  sitekey: 'YOUR_SITE_KEY',
21  callback: (token) => console.log('Success:', token),
22  'error-callback': (code) => console.error('Error:', code)
23});
24```
25 
26### `turnstile.reset(widgetId)`
27 
28Resets a widget (clears token, resets challenge state). Useful when form validation fails.
29 
30**Parameters:**
31- `widgetId` (string): Widget ID from `render()`, or container element
32 
33**Returns:** `void`
34 
35**Example:**
36```javascript
37// Reset on form error
38if (!validateForm()) {
39  window.turnstile.reset(widgetId);
40}
41```
42 
43### `turnstile.remove(widgetId)`
44 
45Removes a widget from the DOM completely.
46 
47**Parameters:**
48- `widgetId` (string): Widget ID from `render()`
49 
50**Returns:** `void`
51 
52**Example:**
53```javascript
54// Cleanup on navigation
55window.turnstile.remove(widgetId);
56```
57 
58### `turnstile.getResponse(widgetId)`
59 
60Gets the current token from a widget (if challenge completed).
61 
62**Parameters:**
63- `widgetId` (string): Widget ID from `render()`, or container element
64 
65**Returns:** `string | undefined` - Token string, or undefined if not ready
66 
67**Example:**
68```javascript
69const token = window.turnstile.getResponse(widgetId);
70if (token) {
71  submitForm(token);
72}
73```
74 
75### `turnstile.isExpired(widgetId)`
76 
77Checks if a widget's token has expired (>5 minutes old).
78 
79**Parameters:**
80- `widgetId` (string): Widget ID from `render()`
81 
82**Returns:** `boolean` - True if expired
83 
84**Example:**
85```javascript
86if (window.turnstile.isExpired(widgetId)) {
87  window.turnstile.reset(widgetId);
88}
89```
90 
91## Callback Signatures
92 
93```typescript
94type TurnstileCallback = (token: string) => void;
95type ErrorCallback = (errorCode: string) => void;
96type TimeoutCallback = () => void;
97type ExpiredCallback = () => void;
98type BeforeInteractiveCallback = () => void;
99type AfterInteractiveCallback = () => void;
100type UnsupportedCallback = () => void;
101```
102 
103## Siteverify API (Server-Side)
104 
105**Endpoint:** `https://challenges.cloudflare.com/turnstile/v0/siteverify`
106 
107### Request
108 
109**Method:** POST  
110**Content-Type:** `application/json` or `application/x-www-form-urlencoded`
111 
112```typescript
113interface SiteverifyRequest {
114  secret: string;    // Your secret key (never expose client-side)
115  response: string;  // Token from cf-turnstile-response
116  remoteip?: string; // User's IP (optional but recommended)
117  idempotency_key?: string; // Unique key for idempotent validation
118}
119```
120 
121**Example:**
122```javascript
123// Cloudflare Workers
124const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
125  method: 'POST',
126  headers: { 'Content-Type': 'application/json' },
127  body: JSON.stringify({
128    secret: env.TURNSTILE_SECRET,
129    response: token,
130    remoteip: request.headers.get('CF-Connecting-IP')
131  })
132});
133const data = await result.json();
134```
135 
136### Response
137 
138```typescript
139interface SiteverifyResponse {
140  success: boolean;           // Validation result
141  challenge_ts?: string;      // ISO timestamp of challenge
142  hostname?: string;          // Hostname where widget was solved
143  'error-codes'?: string[];   // Error codes if success=false
144  action?: string;            // Action name from widget config
145  cdata?: string;             // Custom data from widget config
146}
147```
148 
149**Example Success:**
150```json
151{
152  "success": true,
153  "challenge_ts": "2024-01-15T10:30:00Z",
154  "hostname": "example.com",
155  "action": "login",
156  "cdata": "user123"
157}
158```
159 
160**Example Failure:**
161```json
162{
163  "success": false,
164  "error-codes": ["timeout-or-duplicate"]
165}
166```
167 
168## Error Codes
169 
170| Code | Cause | Solution |
171|------|-------|----------|
172| `missing-input-secret` | Secret key not provided | Include `secret` in request |
173| `invalid-input-secret` | Secret key is wrong | Check secret key in dashboard |
174| `missing-input-response` | Token not provided | Include `response` token |
175| `invalid-input-response` | Token is invalid/malformed | Verify token from widget |
176| `timeout-or-duplicate` | Token expired (>5min) or reused | Generate new token, validate once |
177| `internal-error` | Cloudflare server error | Retry with exponential backoff |
178| `bad-request` | Malformed request | Check JSON/form encoding |
179 
180## TypeScript Types
181 
182```typescript
183interface TurnstileOptions {
184  sitekey: string;
185  action?: string;
186  cData?: string;
187  callback?: (token: string) => void;
188  'error-callback'?: (errorCode: string) => void;
189  'expired-callback'?: () => void;
190  'timeout-callback'?: () => void;
191  'before-interactive-callback'?: () => void;
192  'after-interactive-callback'?: () => void;
193  'unsupported-callback'?: () => void;
194  theme?: 'light' | 'dark' | 'auto';
195  size?: 'normal' | 'compact' | 'flexible';
196  tabindex?: number;
197  'response-field'?: boolean;
198  'response-field-name'?: string;
199  retry?: 'auto' | 'never';
200  'retry-interval'?: number;
201  language?: string;
202  execution?: 'render' | 'execute';
203  appearance?: 'always' | 'execute' | 'interaction-only';
204  'refresh-expired'?: 'auto' | 'manual' | 'never';
205}
206 
207interface Turnstile {
208  render(container: string | HTMLElement, options: TurnstileOptions): string;
209  reset(widgetId: string): void;
210  remove(widgetId: string): void;
211  getResponse(widgetId: string): string | undefined;
212  isExpired(widgetId: string): boolean;
213  execute(container?: string | HTMLElement, options?: TurnstileOptions): void;
214}
215 
216declare global {
217  interface Window {
218    turnstile: Turnstile;
219    onloadTurnstileCallback?: () => void;
220  }
221}
222```
223 
224## Script Loading
225 
226```html
227<!-- Standard -->
228<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
229 
230<!-- Explicit render mode -->
231<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
232 
233<!-- With load callback -->
234<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onloadTurnstileCallback"></script>
235<script>
236window.onloadTurnstileCallback = () => {
237  window.turnstile.render('#container', { sitekey: 'YOUR_SITE_KEY' });
238};
239</script>
240```