# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knock Management API (mAPI) Broadcasts API
  version: 1.0.0
extends: openapi/knock-app-broadcasts-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: 6
- target: $.paths['/v1/broadcasts/{broadcast_key}/send'].put
  update:
    x-apievangelist-phrasing:
      intent: Send or schedule a broadcast
      effect: write
      questions:
      - How do I send a broadcast right away?
      - Can I schedule a broadcast to go out at a later time?
      instructions:
      - text: Send broadcast {broadcast_key} now in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          environment: query.environment
      - text: Schedule broadcast {broadcast_key} to send at {send_at} in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          send_at: requestBody.send_at
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/broadcasts/{broadcast_key}/validate'].put
  update:
    x-apievangelist-phrasing:
      intent: Validate a broadcast without saving
      effect: read
      questions:
      - Can I check a broadcast payload for errors before saving it?
      - Is there a way to dry-run a broadcast definition?
      instructions:
      - text: Validate broadcast payload {broadcast} for key {broadcast_key} in {environment}.
        slots:
          broadcast: requestBody.broadcast
          broadcast_key: path.broadcast_key
          environment: query.environment
      - text: Check broadcast {broadcast_key} definition {broadcast} without persisting it in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          broadcast: requestBody.broadcast
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/broadcasts'].get
  update:
    x-apievangelist-phrasing:
      intent: List broadcasts in an environment
      effect: read
      questions:
      - Which broadcasts have been created in this environment, newest first?
      - Can I page through broadcasts on a specific branch?
      instructions:
      - text: List broadcasts in {environment}.
        slots:
          environment: query.environment
      - text: Show the latest {limit} broadcasts on branch {branch} in {environment}.
        slots:
          limit: query.limit
          branch: query.branch
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/broadcasts/{broadcast_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a broadcast by key
      effect: read
      questions:
      - How do I see the details and status of one broadcast?
      - Can I fetch a broadcast without its uncommitted edits?
      instructions:
      - text: Get broadcast {broadcast_key} in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          environment: query.environment
      - text: Show me the {broadcast_key} broadcast.
        slots:
          broadcast_key: path.broadcast_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/broadcasts/{broadcast_key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a broadcast
      effect: write
      questions:
      - How do I create a broadcast or edit an existing draft?
      - Can I update a broadcast's content by its key?
      instructions:
      - text: Upsert broadcast {broadcast_key} in {environment} with {broadcast}.
        slots:
          broadcast_key: path.broadcast_key
          environment: query.environment
          broadcast: requestBody.broadcast
      - text: Save a new broadcast {broadcast_key} using definition {broadcast} in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          broadcast: requestBody.broadcast
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/broadcasts/{broadcast_key}/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel a scheduled broadcast
      effect: destructive
      questions:
      - How do I stop a broadcast that's scheduled but hasn't gone out yet?
      - Does cancelling a scheduled broadcast put it back into draft?
      instructions:
      - text: Cancel scheduled broadcast {broadcast_key} in {environment}.
        slots:
          broadcast_key: path.broadcast_key
          environment: query.environment
      - text: Unschedule the {broadcast_key} broadcast and return it to draft.
        slots:
          broadcast_key: path.broadcast_key
      method: generated
      generated: '2026-10-01'