# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cloudflare Turnstile Widgets API
  version: 1.0.0
extends: openapi/cloudflare-widgets-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/accounts/{account_id}/challenges/widgets'].get
  update:
    x-apievangelist-phrasing:
      intent: List Turnstile widgets
      effect: read
      questions:
      - Which Turnstile widgets are configured in my Cloudflare account?
      - Can I see all my Turnstile site keys in one place?
      instructions:
      - text: List every Turnstile widget in account {account}.
        slots:
          account: path.account_id
      - text: Show me all my Turnstile widgets and their site keys.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{account_id}/challenges/widgets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Turnstile widget
      effect: write
      questions:
      - How do I create a new Turnstile widget for my website?
      - Can I restrict a new CAPTCHA-alternative widget to specific domains and pick its mode?
      - Is bot fight mode something I can switch on when setting up a widget?
      instructions:
      - text: Create a Turnstile widget named {name} for domains {domains} in {mode} mode.
        slots:
          name: requestBody.name
          domains: requestBody.domains
          mode: requestBody.mode
      - text: Add a new Turnstile widget {name} in account {account} allowed on {domains}.
        slots:
          name: requestBody.name
          account: path.account_id
          domains: requestBody.domains
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{account_id}/challenges/widgets/{sitekey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Turnstile widget's configuration
      effect: read
      questions:
      - What domains and mode is a particular Turnstile widget set to?
      - Can I look up one Turnstile widget's settings by its site key?
      instructions:
      - text: Get the Turnstile widget with site key {sitekey}.
        slots:
          sitekey: path.sitekey
      - text: Show the configuration of Turnstile widget {sitekey} in account {account}.
        slots:
          sitekey: path.sitekey
          account: path.account_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{account_id}/challenges/widgets/{sitekey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Turnstile widget's settings
      effect: write
      questions:
      - How do I add another allowed domain to an existing Turnstile widget?
      - Can I change the mode of a Turnstile widget I already created?
      instructions:
      - text: Update Turnstile widget {sitekey} to allow domains {domains}.
        slots:
          sitekey: path.sitekey
          domains: requestBody.domains
      - text: Switch existing widget {sitekey} in account {account} to {mode} mode and rename it {name}.
        slots:
          account: path.account_id
          sitekey: path.sitekey
          mode: requestBody.mode
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{account_id}/challenges/widgets/{sitekey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Turnstile widget
      effect: destructive
      questions:
      - How do I remove a Turnstile widget I'm not using anymore?
      - What happens to a site key when its Turnstile widget is deleted?
      instructions:
      - text: Delete the Turnstile widget with site key {sitekey}.
        slots:
          sitekey: path.sitekey
      - text: Remove Turnstile widget {sitekey} from account {account}.
        slots:
          sitekey: path.sitekey
          account: path.account_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a Turnstile widget's secret key
      effect: write
      questions:
      - How do I rotate the secret key for a Turnstile widget?
      - Does the old Turnstile secret keep working for a while after I rotate it?
      instructions:
      - text: Rotate the secret key for Turnstile widget {sitekey}.
        slots:
          sitekey: path.sitekey
      - text: Generate a new secret for widget {sitekey} in account {account}.
        slots:
          sitekey: path.sitekey
          account: path.account_id
      method: generated
      generated: '2026-09-26'