# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knock App Workflows API
  version: 1.0.0
extends: openapi/knock-app-workflows-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: 9
- target: $.paths['/v1/workflows/{workflow_key}/validate'].put
  update:
    x-apievangelist-phrasing:
      intent: Validate a workflow without saving
      effect: read
      questions:
      - Can I check a workflow definition for errors before saving it?
      - Is there a dry run for workflow payloads?
      instructions:
      - text: Validate workflow payload {workflow} for {workflow_key} in {environment}.
        slots:
          workflow: requestBody.workflow
          workflow_key: path.workflow_key
          environment: query.environment
      - text: Check workflow {workflow_key} definition {workflow} without persisting it in {environment}.
        slots:
          workflow_key: path.workflow_key
          workflow: requestBody.workflow
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{workflow_key}/run'].put
  update:
    x-apievangelist-phrasing:
      intent: Run a committed workflow in an environment
      effect: write
      questions:
      - How do I run the latest committed version of a workflow in a chosen environment?
      - Can I run a workflow on a specific branch for testing?
      instructions:
      - text: Run workflow {workflow_key} in {environment} for {recipients}.
        slots:
          workflow_key: path.workflow_key
          environment: query.environment
          recipients: requestBody.recipients
      - text: Run committed workflow {workflow_key} on branch {branch} in {environment} for {recipients}.
        slots:
          workflow_key: path.workflow_key
          branch: query.branch
          environment: query.environment
          recipients: requestBody.recipients
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{workflow_key}/steps/{step_ref}/preview_template'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a workflow step's template
      effect: read
      questions:
      - How do I see what a workflow step's message will look like for a recipient?
      - Can I render a channel step's template with sample data?
      instructions:
      - text: Preview step {step_ref} of workflow {workflow_key} for {recipient} in {environment}.
        slots:
          step_ref: path.step_ref
          workflow_key: path.workflow_key
          recipient: requestBody.recipient
          environment: query.environment
      - text: Render workflow {workflow_key} step {step_ref} for {recipient} with data {data} in {environment}.
        slots:
          workflow_key: path.workflow_key
          step_ref: path.step_ref
          recipient: requestBody.recipient
          data: requestBody.data
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows'].get
  update:
    x-apievangelist-phrasing:
      intent: List workflows
      effect: read
      questions:
      - Which workflows are defined in this environment?
      - In what order are workflows listed?
      instructions:
      - text: List workflows in {environment}.
        slots:
          environment: query.environment
      - text: Show {limit} workflows on branch {branch} in {environment}.
        slots:
          limit: query.limit
          branch: query.branch
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{workflow_key}/activate'].put
  update:
    x-apievangelist-phrasing:
      intent: Activate or deactivate a workflow
      effect: write
      questions:
      - How do I turn a workflow off in production?
      - Does activating a workflow take effect immediately?
      instructions:
      - text: Set workflow {workflow_key} status to {status} in {environment}.
        slots:
          workflow_key: path.workflow_key
          status: requestBody.status
          environment: query.environment
      - text: Activate the {workflow_key} workflow in {environment} with status {status}.
        slots:
          workflow_key: path.workflow_key
          environment: query.environment
          status: requestBody.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{workflow_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workflow by key
      effect: read
      questions:
      - How do I see a workflow's steps and settings?
      - Can I fetch a workflow without its uncommitted changes?
      instructions:
      - text: Get workflow {workflow_key} in {environment}.
        slots:
          workflow_key: path.workflow_key
          environment: query.environment
      - text: Show the {workflow_key} workflow definition.
        slots:
          workflow_key: path.workflow_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{workflow_key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a workflow
      effect: write
      questions:
      - How do I create a new notification workflow in development?
      - Can I commit a workflow change as I save it?
      instructions:
      - text: Upsert workflow {workflow_key} in {environment} with {workflow}.
        slots:
          workflow_key: path.workflow_key
          environment: query.environment
          workflow: requestBody.workflow
      - text: Save workflow {workflow_key} and commit with message {commit_message} in {environment}.
        slots:
          workflow_key: path.workflow_key
          commit_message: query.commit_message
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{key}/trigger'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger a workflow by key
      effect: write
      questions:
      - How do I send a notification by triggering a workflow for some users?
      - Can I pass a cancellation key when triggering so I can cancel later?
      - Do Knock workflow triggers run synchronously?
      instructions:
      - text: Trigger workflow {key} for {recipients}.
        slots:
          key: path.key
          recipients: requestBody.recipients
      - text: Trigger workflow {key} for {recipients} with data {data} and cancellation key {cancellation_key}.
        slots:
          key: path.key
          recipients: requestBody.recipients
          data: requestBody.data
          cancellation_key: requestBody.cancellation_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/workflows/{key}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel queued runs of a workflow
      effect: destructive
      questions:
      - How do I cancel a delayed notification before it sends?
      - Can I cancel a workflow run for only certain recipients?
      instructions:
      - text: Cancel workflow {key} runs with cancellation key {cancellation_key}.
        slots:
          key: path.key
          cancellation_key: requestBody.cancellation_key
      - text: Cancel workflow {key} for {recipients} using cancellation key {cancellation_key}.
        slots:
          key: path.key
          recipients: requestBody.recipients
          cancellation_key: requestBody.cancellation_key
      method: generated
      generated: '2026-10-01'