# 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 Guides API
  version: 1.0.0
extends: openapi/knock-app-guides-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: 15
- target: $.paths['/v1/guides/{guide_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an in-app guide by key
      effect: read
      questions:
      - How do I view one guide's steps and targeting?
      - Can I fetch a guide as it exists on a branch?
      instructions:
      - text: Get guide {guide_key} in {environment}.
        slots:
          guide_key: path.guide_key
          environment: query.environment
      - text: Show the {guide_key} guide definition on branch {branch} in {environment}.
        slots:
          guide_key: path.guide_key
          branch: query.branch
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/guides/{guide_key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an in-app guide
      effect: write
      questions:
      - How do I create a new onboarding guide or edit an existing one?
      - Can I commit a guide change as soon as I save it?
      instructions:
      - text: Upsert guide {guide_key} in {environment} with {guide}.
        slots:
          guide_key: path.guide_key
          environment: query.environment
          guide: requestBody.guide
      - text: Save guide {guide_key} and commit with message {commit_message} in {environment}.
        slots:
          guide_key: path.guide_key
          commit_message: query.commit_message
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/guides/{guide_key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive a guide in every environment
      effect: destructive
      questions:
      - How do I retire a guide across all environments?
      - What happens to a guide when I archive it?
      instructions:
      - text: Archive guide {guide_key}.
        slots:
          guide_key: path.guide_key
      - text: Retire the {guide_key} guide everywhere.
        slots:
          guide_key: path.guide_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/guides'].get
  update:
    x-apievangelist-phrasing:
      intent: List guides in an environment
      effect: read
      questions:
      - Which in-app guides are defined in this environment?
      - Can I page through guides on a branch?
      instructions:
      - text: List guides in {environment}.
        slots:
          environment: query.environment
      - text: Show {limit} guides on branch {branch} in {environment}.
        slots:
          limit: query.limit
          branch: query.branch
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/guides/{guide_key}/activate'].put
  update:
    x-apievangelist-phrasing:
      intent: Activate or deactivate a guide
      effect: write
      questions:
      - How do I turn a guide on so users start seeing it?
      - Can I schedule when a guide becomes active?
      instructions:
      - text: Activate guide {guide_key} in {environment}.
        slots:
          guide_key: path.guide_key
          environment: query.environment
      - text: Deactivate the {guide_key} guide in {environment}.
        slots:
          guide_key: path.guide_key
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/guides/{guide_key}/validate'].put
  update:
    x-apievangelist-phrasing:
      intent: Validate a guide without saving
      effect: read
      questions:
      - Can I check a guide payload for errors before saving it?
      - Is there a dry run for guide definitions?
      instructions:
      - text: Validate guide payload {guide} for {guide_key} in {environment}.
        slots:
          guide: requestBody.guide
          guide_key: path.guide_key
          environment: query.environment
      - text: Check guide {guide_key} definition {guide} without persisting it in {environment}.
        slots:
          guide_key: path.guide_key
          guide: requestBody.guide
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/seen'].put
  update:
    x-apievangelist-phrasing:
      intent: Record a guide as seen (no message ID)
      effect: write
      questions:
      - How do I record that a user saw a guide step when I don't have a guide message ID?
      - Can I log a guide view using only the guide key and step reference?
      instructions:
      - text: Mark step {guide_step_ref} of guide {guide_key} as seen for user {user_id}, without a message ID.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Log a seen event on guide {guide_key} step {guide_step_ref} for {user_id} via the message-less endpoint.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/{message_id}/seen'].put
  update:
    x-apievangelist-phrasing:
      intent: Record an existing guide message as seen
      effect: write
      questions:
      - How do I mark a specific guide message as seen for a user?
      - Does marking a guide message seen trigger the guide's seen events?
      instructions:
      - text: Mark guide message {message_id} for {guide_key} step {guide_step_ref} as seen by user {user_id}.
        slots:
          user_id: path.user_id
          message_id: path.message_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Record that user {user_id} viewed their existing guide message for {guide_key} step {guide_step_ref}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/archived'].put
  update:
    x-apievangelist-phrasing:
      intent: Record a guide as dismissed (no message ID)
      effect: write
      questions:
      - How do I archive a guide for a user when I have no guide message ID?
      - Can a user dismiss a guide using just its key and step?
      instructions:
      - text: Mark guide {guide_key} step {guide_step_ref} as archived for user {user_id}, without a message ID.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Dismiss guide {guide_key} at step {guide_step_ref} for {user_id} via the message-less endpoint.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/archived'].delete
  update:
    x-apievangelist-phrasing:
      intent: Restore a dismissed guide
      effect: destructive
      questions:
      - How do I bring back a guide a user previously dismissed?
      - Can I undo a guide archive for one user?
      instructions:
      - text: Unarchive guide {guide_key} step {guide_step_ref} for user {user_id}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Restore the dismissed {guide_key} guide for {user_id} at step {guide_step_ref}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/interacted'].put
  update:
    x-apievangelist-phrasing:
      intent: Record a guide interaction (no message ID)
      effect: write
      questions:
      - How do I log a user clicking inside a guide when I lack a guide message ID?
      - Can I record a guide interaction from only the guide key and step?
      instructions:
      - text: Mark guide {guide_key} step {guide_step_ref} as interacted for user {user_id}, without a message ID.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Log an interaction on guide {guide_key} step {guide_step_ref} by {user_id} via the message-less endpoint.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/engagements/reset'].put
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's engagement with a guide
      effect: write
      questions:
      - How do I reset a guide so a user's next interaction starts fresh?
      - Can I clear a user's engagement history on one guide?
      instructions:
      - text: Reset engagement on guide {guide_key} step {guide_step_ref} for user {user_id}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Clear user {user_id}'s engagement log for the {guide_key} guide at step {guide_step_ref}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/{channel_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List guides a user is eligible for
      effect: read
      questions:
      - Which in-app guides should a particular user see right now?
      - Can I list a user's eligible guides for a specific tenant?
      instructions:
      - text: List eligible guides for user {user_id} on channel {channel_id}.
        slots:
          user_id: path.user_id
          channel_id: path.channel_id
      - text: Show guides user {user_id} qualifies for on channel {channel_id} in tenant {tenant}.
        slots:
          user_id: path.user_id
          channel_id: path.channel_id
          tenant: query.tenant
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/{message_id}/interacted'].put
  update:
    x-apievangelist-phrasing:
      intent: Record an interaction on a guide message
      effect: write
      questions:
      - How do I record that a user interacted with a specific guide message?
      - Does logging a guide message interaction trigger its interacted events?
      instructions:
      - text: Mark guide message {message_id} for {guide_key} step {guide_step_ref} as interacted by user {user_id}.
        slots:
          user_id: path.user_id
          message_id: path.message_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Record user {user_id} clicking their existing guide message for {guide_key} step {guide_step_ref}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/guides/messages/{message_id}/archived'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive an existing guide message
      effect: write
      questions:
      - How do I archive a specific guide message a user dismissed?
      - Will archiving a guide message fire its archived events?
      instructions:
      - text: Archive guide message {message_id} for {guide_key} step {guide_step_ref} for user {user_id}.
        slots:
          user_id: path.user_id
          message_id: path.message_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      - text: Record that user {user_id} dismissed their existing guide message for {guide_key} step {guide_step_ref}.
        slots:
          user_id: path.user_id
          guide_key: requestBody.guide_key
          guide_step_ref: requestBody.guide_step_ref
      method: generated
      generated: '2026-10-01'