# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Webhooks API
  version: 1.0.0
extends: openapi/bitbucket-webhooks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 12
- target: $.paths['/hook_events'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhook subject types
      effect: read
      questions:
      - What kinds of things can I attach webhooks to?
      - Which resource types support webhooks?
      instructions:
      - text: List the resource types that accept webhooks.
      - text: Show all webhook subject types.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/hook_events/{subject_type}'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhook events for a subject type
      effect: read
      questions:
      - Which events can a repository webhook subscribe to?
      - What event names are valid for workspace webhooks?
      instructions:
      - text: List subscribable webhook events for {subject_type}.
        slots:
          subject_type: path.subject_type
      - text: Show the event names available on {subject_type} webhooks.
        slots:
          subject_type: path.subject_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's webhooks
      effect: read
      questions:
      - What webhooks are installed on this repository?
      - Is any webhook on my repo pointing at an old URL?
      instructions:
      - text: List webhooks on repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every repo-level hook in {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a repository webhook
      effect: write
      questions:
      - How do I get notified when someone pushes to one repo?
      - Can a repository webhook sign its payloads with a secret?
      instructions:
      - text: Create a webhook on repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Add a push webhook to repo {repo_slug} in {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a repository webhook
      effect: read
      questions:
      - Which events does a particular repo webhook fire on?
      - Can I check whether a repository webhook is active?
      instructions:
      - text: Get webhook {uid} on repository {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show repo hook {uid}'s events and URL.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a repository webhook
      effect: write
      questions:
      - How do I change the URL of a repo webhook?
      - Can I pause a repository webhook without deleting it?
      instructions:
      - text: Update webhook {uid} on repository {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Deactivate repo hook {uid} in {repo_slug}.
        slots:
          uid: path.uid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a repository webhook
      effect: destructive
      questions:
      - How do I remove a webhook from one repository?
      - Can I delete a repo hook that keeps failing?
      instructions:
      - text: Delete webhook {uid} from repository {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove repo hook {uid} in {repo_slug}.
        slots:
          uid: path.uid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a workspace's webhooks
      effect: read
      questions:
      - Which webhooks fire for every repo in my workspace?
      - What workspace-level hooks are configured?
      instructions:
      - text: List webhooks on workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show all workspace-wide hooks in {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a workspace webhook
      effect: write
      questions:
      - Can one webhook cover all repositories in my workspace?
      - How do I subscribe to events across the whole workspace?
      instructions:
      - text: Create a webhook on workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Add a workspace-wide hook in {workspace} for all repositories.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workspace webhook
      effect: read
      questions:
      - What does a specific workspace-level webhook subscribe to?
      - Is a given workspace hook still active?
      instructions:
      - text: Get webhook {uid} on workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Show workspace hook {uid}'s settings.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a workspace webhook
      effect: write
      questions:
      - How do I rotate the secret on a workspace webhook?
      - Can I change which events a workspace hook listens for?
      instructions:
      - text: Update webhook {uid} on workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Change the events on workspace hook {uid} in {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a workspace webhook
      effect: destructive
      questions:
      - How do I remove a workspace-wide webhook?
      - Can I delete a workspace hook by its id?
      instructions:
      - text: Delete webhook {uid} from workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Remove workspace hook {uid}.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-10-01'