# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Onesignal Apps API
  version: 1.0.0
extends: openapi/onesignal-apps-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: 42
- target: $.paths['/apps'].get
  update:
    x-apievangelist-phrasing:
      intent: List all apps in my OneSignal account
      effect: read
      questions:
      - Which OneSignal apps does my organization have?
      - Can I see the subscriber counts for every app I manage at once?
      instructions:
      - text: List all of my OneSignal apps with their app IDs and subscriber counts.
      - text: Show every app on my account and when each was created.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new app
      effect: write
      questions:
      - How do I create a new OneSignal app through the API?
      - What do I need to set up web push when creating an app?
      - Can I configure iOS and Android push credentials at the moment I create an app?
      instructions:
      - text: Create a new app called {name} in organization {organization_id}.
        slots:
          name: requestBody.name
          organization_id: requestBody.organization_id
      - text: Create app {name} under organization {organization_id} with web push for site {chrome_web_origin}.
        slots:
          name: requestBody.name
          organization_id: requestBody.organization_id
          chrome_web_origin: requestBody.chrome_web_origin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one app's details
      effect: read
      questions:
      - What settings and platform configuration does a single app have?
      - Can I look up one app's details by its app ID?
      instructions:
      - text: Show me the details of app {app_id}.
        slots:
          app_id: path.app_id
      - text: Get app {app_id} and tell me its name and subscriber count.
        slots:
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an app's name or push configuration
      effect: write
      questions:
      - How do I rename an existing app?
      - Can I replace the APNs or FCM credentials on an app I already created?
      instructions:
      - text: Rename app {app_id} to {name}.
        slots:
          app_id: path.app_id
          name: requestBody.name
      - text: Change the APNs environment on existing app {app_id} to {apns_env}.
        slots:
          app_id: path.app_id
          apns_env: requestBody.apns_env
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List an app's segments
      effect: read
      questions:
      - What audience segments exist in my app?
      - Can I page through segments if my app has a lot of them?
      instructions:
      - text: List all segments in app {app_id}.
        slots:
          app_id: path.app_id
      - text: Show {limit} segments from app {app_id} starting at offset {offset}.
        slots:
          limit: query.limit
          app_id: path.app_id
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an audience segment
      effect: write
      questions:
      - How do I build a new audience segment with filters?
      - Can I define a segment by tags or activity rules through the API?
      instructions:
      - text: Create a segment named {name} in app {app_id} using filters {filters}.
        slots:
          name: requestBody.name
          app_id: path.app_id
          filters: requestBody.filters
      - text: Add a new segment {name} to app {app_id} with filters {filters} and description {description}.
        slots:
          name: requestBody.name
          app_id: path.app_id
          filters: requestBody.filters
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/segments/{segment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one segment and its subscriber count
      effect: read
      questions:
      - How many subscribers are in a particular segment right now?
      - Can I see the filters behind a single segment?
      instructions:
      - text: Show me segment {segment_id} in app {app_id}.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
      - text: Get segment {segment_id} from app {app_id} including its filters and metadata.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/segments/{segment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment
      effect: destructive
      questions:
      - Does deleting a segment also remove the users in it?
      - How do I get rid of a segment I no longer use?
      instructions:
      - text: Delete segment {segment_id} from app {app_id}.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
      - text: Remove the unused segment {segment_id} in app {app_id}, keeping its users.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/segments/{segment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or change the filters of a segment
      effect: write
      questions:
      - If I change a segment's filters, are the old filters replaced or merged?
      - Can I rename an existing segment without recreating it?
      instructions:
      - text: Rename segment {segment_id} in app {app_id} to {name}.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
          name: requestBody.name
      - text: Replace the filters on existing segment {segment_id} in app {app_id} with {filters}, keeping the name {name}.
        slots:
          segment_id: path.segment_id
          app_id: path.app_id
          filters: requestBody.filters
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}'].get
  update:
    x-apievangelist-phrasing:
      intent: View outcome metrics for an app
      effect: read
      questions:
      - How many clicks and conversions did my push notifications drive?
      - Can I filter outcome metrics by platform or attribution type?
      instructions:
      - text: Show outcomes {outcome_names} for app {app_id} over {outcome_time_range}.
        slots:
          outcome_names: query.outcome_names
          app_id: path.app_id
          outcome_time_range: query.outcome_time_range
      - text: Report outcome {outcome_names} for app {app_id} on platforms {outcome_platforms} with {outcome_attribution} attribution.
        slots:
          outcome_names: query.outcome_names
          app_id: path.app_id
          outcome_platforms: query.outcome_platforms
          outcome_attribution: query.outcome_attribution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions/{subscription_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subscription
      effect: destructive
      questions:
      - How do I stop sending messages to one specific device or email subscription?
      - If I delete a subscription, can the same token subscribe again later?
      instructions:
      - text: Delete subscription {subscription_id} from app {app_id}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
      - text: Permanently remove subscription {subscription_id} in app {app_id} so it gets no more messages.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions/{subscription_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription by its ID
      effect: write
      questions:
      - How do I disable a subscription when I know its subscription ID?
      - Can I re-enable a subscription from my backend instead of through the SDK?
      instructions:
      - text: Update subscription {subscription_id} in app {app_id} with {subscription}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
          subscription: requestBody.subscription
      - text: Disable subscription ID {subscription_id} in app {app_id}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions_by_token/{token_type}/{token}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription by its push token or address
      effect: write
      questions:
      - Can I update a subscription when I only have its push token or email address?
      - How do I turn off a subscription identified by token type and token?
      instructions:
      - text: Disable the {token_type} subscription with token {token} in app {app_id}.
        slots:
          token_type: path.token_type
          token: path.token
          app_id: path.app_id
      - text: Update the subscription for {token_type} token {token} in app {app_id} with {subscription}.
        slots:
          token_type: path.token_type
          token: path.token
          app_id: path.app_id
          subscription: requestBody.subscription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a subscription to an existing user
      effect: write
      questions:
      - How do I attach an email or SMS subscription to a user I already have?
      - Can I add a new push subscription to a user identified by their external ID?
      instructions:
      - text: Add subscription {subscription} to the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          subscription: requestBody.subscription
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Attach a new email subscription {subscription} to user {alias_id} (by {alias_label}) in app {app_id}.
        slots:
          subscription: requestBody.subscription
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a user with their properties and subscriptions
      effect: read
      questions:
      - What properties, tags and subscriptions does a given user have?
      - Can I look up a user by their external ID?
      instructions:
      - text: Show me the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Get the full profile and subscriptions of user {alias_id} by {alias_label} in app {app_id}.
        slots:
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user and all their subscriptions
      effect: destructive
      questions:
      - How do I completely delete a user and everything attached to them?
      - Does deleting a user also remove their subscriptions and aliases?
      instructions:
      - text: Delete the user with {alias_label} {alias_id} from app {app_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Erase user {alias_id} (by {alias_label}) in app {app_id} along with their subscriptions and identity.
        slots:
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's properties and tags
      effect: write
      questions:
      - How do I change tags or language on an existing user?
      - Can I increment a user's session count or purchase totals with deltas?
      instructions:
      - text: Set properties {properties} on the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          properties: requestBody.properties
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Apply deltas {deltas} to user {alias_id} by {alias_label} in app {app_id}.
        slots:
          deltas: requestBody.deltas
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user with identity and subscriptions
      effect: write
      questions:
      - How do I create a new user along with their email and push subscriptions?
      - Can I register a user with an external ID and tags in one call?
      instructions:
      - text: Create a user in app {app_id} with identity {identity}.
        slots:
          app_id: path.app_id
          identity: requestBody.identity
      - text: Create a new user in app {app_id} with identity {identity} and subscriptions {subscriptions}.
        slots:
          app_id: path.app_id
          identity: requestBody.identity
          subscriptions: requestBody.subscriptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up all aliases for a user from one alias
      effect: read
      questions:
      - Given a user's external ID, how do I find their OneSignal ID and other aliases?
      - Which identities are linked to a user I know by one alias?
      instructions:
      - text: List every alias for the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Map user {alias_id} (known by {alias_label}) in app {app_id} to their full identity.
        slots:
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add or update aliases on a user by alias
      effect: write
      questions:
      - How do I add a custom alias to a user I already know by external ID?
      - Can I update several aliases on a user's identity at once?
      instructions:
      - text: Add aliases {identity} to the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          identity: requestBody.identity
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Upsert identity {identity} for user {alias_id} found by {alias_label} in app {app_id}.
        slots:
          identity: requestBody.identity
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions/{subscription_id}/owner'].patch
  update:
    x-apievangelist-phrasing:
      intent: Move a subscription to a different user
      effect: write
      questions:
      - How do I reassign a push or email subscription to another user?
      - Can a subscription be transferred to a new user identity within the same app?
      instructions:
      - text: Transfer subscription {subscription_id} in app {app_id} to the user with identity {identity}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
          identity: requestBody.identity
      - text: Change the owner of subscription {subscription_id} in app {app_id} to {identity}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
          identity: requestBody.identity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions/{subscription_id}/user/identity'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user's aliases from a subscription ID
      effect: read
      questions:
      - Who owns this subscription, and what are their aliases?
      - Can I find a user's external ID when all I have is a subscription ID?
      instructions:
      - text: Show the aliases of the user who owns subscription {subscription_id} in app {app_id}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
      - text: Find the identity behind subscription {subscription_id} in app {app_id}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/subscriptions/{subscription_id}/user/identity'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add an alias to a user via their subscription ID
      effect: write
      questions:
      - How do I set an external ID on a user when I only know one of their subscription IDs?
      - Can I create an alias through a subscription instead of an existing alias?
      instructions:
      - text: Add alias {identity} to the user owning subscription {subscription_id} in app {app_id}.
        slots:
          identity: requestBody.identity
          subscription_id: path.subscription_id
          app_id: path.app_id
      - text: Using subscription {subscription_id} in app {app_id}, set that user's identity to include {identity}.
        slots:
          subscription_id: path.subscription_id
          app_id: path.app_id
          identity: requestBody.identity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an alias from a user
      effect: destructive
      questions:
      - How do I remove one alias from a user without deleting the user?
      - Can I drop a custom alias label from someone's identity?
      instructions:
      - text: Remove the {alias_label_to_delete} alias from the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          alias_label_to_delete: path.alias_label_to_delete
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Delete alias label {alias_label_to_delete} from user {alias_id} (by {alias_label}) in app {app_id}.
        slots:
          alias_label_to_delete: path.alias_label_to_delete
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe an email address from a custom page
      effect: write
      questions:
      - How does my own unsubscribe page opt someone out of emails?
      - What token do I need to unsubscribe an email recipient from a specific message?
      instructions:
      - text: Unsubscribe the email recipient with token {token} from message {notification_id} in app {app_id}.
        slots:
          token: query.token
          notification_id: path.notification_id
          app_id: path.app_id
      - text: Process an unsubscribe from my custom landing page for notification {notification_id} in app {app_id}.
        slots:
          notification_id: path.notification_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/live_activities/{activity_id}/notifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Update or end a running iOS Live Activity
      effect: write
      questions:
      - How do I push new content to a Live Activity that's already running?
      - Can I end a Live Activity remotely and set when it gets dismissed?
      instructions:
      - text: Update Live Activity {activity_id} in app {app_id} with {event_updates}, named {name}, event {event}.
        slots:
          activity_id: path.activity_id
          app_id: path.app_id
          event_updates: requestBody.event_updates
          name: requestBody.name
          event: requestBody.event
      - text: End Live Activity {activity_id} in app {app_id} with event {event}, final state {event_updates}, name {name}, dismissed at {dismissal_date}.
        slots:
          activity_id: path.activity_id
          app_id: path.app_id
          event: requestBody.event
          event_updates: requestBody.event_updates
          name: requestBody.name
          dismissal_date: requestBody.dismissal_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/activities/activity/{activity_type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Live Activity on users' iOS devices
      effect: write
      questions:
      - Can I remotely start an iOS Live Activity without the user opening my app?
      - Which users or segments can I target when starting a Live Activity?
      instructions:
      - text: Start a {activity_type} Live Activity {activity_id} in app {app_id} for segments {included_segments}.
        slots:
          activity_type: path.activity_type
          activity_id: requestBody.activity_id
          app_id: path.app_id
          included_segments: requestBody.included_segments
      - text: Launch Live Activity type {activity_type} in app {app_id} with heading {headings} and message {contents}.
        slots:
          activity_type: path.activity_type
          app_id: path.app_id
          headings: requestBody.headings
          contents: requestBody.contents
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/inbox'].post
  update:
    x-apievangelist-phrasing:
      intent: Broadcast a message to users' in-app inboxes
      effect: write
      questions:
      - How do I post a message to every user's in-app inbox?
      - Can I schedule an inbox broadcast to appear later?
      instructions:
      - text: Broadcast inbox message {name} with subject {subjects} to app {app_id}.
        slots:
          name: requestBody.name
          subjects: requestBody.subjects
          app_id: path.app_id
      - text: Schedule inbox broadcast {name} in app {app_id} with subject {subjects} for {send_after}.
        slots:
          name: requestBody.name
          app_id: path.app_id
          subjects: requestBody.subjects
          send_after: requestBody.send_after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/inbox?last_broadcast_id={broadcast_id}&limit={number}'].get
  update:
    x-apievangelist-phrasing:
      intent: List inbox broadcasts sent by an app
      effect: read
      questions:
      - What inbox broadcasts has my app sent to its audience?
      - Can I page through older inbox broadcasts after a given one?
      instructions:
      - text: List the inbox broadcasts for app {app_id}.
        slots:
          app_id: path.app_id
      - text: Show {limit} inbox broadcasts in app {app_id} after broadcast {last_broadcast_id}.
        slots:
          limit: query.limit
          app_id: path.app_id
          last_broadcast_id: query.last_broadcast_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox?last_message_id={message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List the inbox messages one user received
      effect: read
      questions:
      - Which inbox messages has a specific user received?
      - Can I see one person's inbox history starting after a certain message?
      instructions:
      - text: Show the inbox messages for user {alias_id} by {alias_label} in app {app_id} after message {last_message_id}.
        slots:
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
          last_message_id: query.last_message_id
      - text: List what's in the inbox of the user with {alias_label} {alias_id} in app {app_id}, after {last_message_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
          last_message_id: query.last_message_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox?last_message_id={message_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark many inbox messages read or deleted for a user
      effect: write
      questions:
      - How do I mark all of a user's inbox messages as read at once?
      - Can I clear a user's whole inbox in a single request?
      instructions:
      - text: Mark all inbox messages as read for the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Set is_deleted to {is_deleted} on every inbox message up to {last_message_id} for user {alias_id} by {alias_label} in app {app_id}.
        slots:
          is_deleted: requestBody.is_deleted
          last_message_id: query.last_message_id
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox/unread_count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's unread inbox messages
      effect: read
      questions:
      - How many unread inbox messages does a user have?
      - What number should I show on a user's inbox badge?
      instructions:
      - text: Get the unread inbox count for the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Tell me how many unread messages user {alias_id} (by {alias_label}) has in app {app_id}.
        slots:
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox/{message_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark a single inbox message read, opened or deleted
      effect: write
      questions:
      - How do I mark just one inbox message as opened?
      - Can I delete a single message from a user's inbox?
      instructions:
      - text: Mark inbox message {message_id} as read for the user with {alias_label} {alias_id} in app {app_id}.
        slots:
          message_id: path.message_id
          alias_label: path.alias_label
          alias_id: path.alias_id
          app_id: path.app_id
      - text: Set is_opened to {is_opened} on message {message_id} for user {alias_id} by {alias_label} in app {app_id}.
        slots:
          is_opened: requestBody.is_opened
          message_id: path.message_id
          alias_id: path.alias_id
          alias_label: path.alias_label
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/auth/tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List an app's API keys
      effect: read
      questions:
      - What API keys currently exist for my app?
      - Can I review the IP allowlist settings on my app's keys?
      instructions:
      - text: List all API keys for app {app_id}.
        slots:
          app_id: path.app_id
      - text: Show the Rich Authentication Tokens configured on app {app_id}.
        slots:
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/auth/tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an app API key
      effect: write
      questions:
      - How do I generate a new REST API key for one of my apps?
      - Can I restrict a new app key to specific IP addresses?
      instructions:
      - text: Create an API key named {name} for app {app_id}.
        slots:
          name: requestBody.name
          app_id: path.app_id
      - text: Create key {name} on app {app_id} limited to IPs {ip_allowlist}.
        slots:
          name: requestBody.name
          app_id: path.app_id
          ip_allowlist: requestBody.ip_allowlist
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/auth/tokens/{token_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app API key
      effect: destructive
      questions:
      - How do I revoke an app API key I no longer need?
      - Do I delete a key by its token value or by its ID?
      instructions:
      - text: Delete API key {token_id} from app {app_id}.
        slots:
          token_id: path.token_id
          app_id: path.app_id
      - text: Revoke key ID {token_id} on app {app_id} permanently.
        slots:
          token_id: path.token_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/auth/tokens/{token_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename an API key or change its IP allowlist
      effect: write
      questions:
      - Can I change the IP allowlist on an existing app key?
      - How do I rename an API key without rotating it?
      instructions:
      - text: Rename API key {token_id} on app {app_id} to {name}.
        slots:
          token_id: path.token_id
          app_id: path.app_id
          name: requestBody.name
      - text: Set the IP allowlist of key {token_id} in app {app_id} to {ip_allowlist}.
        slots:
          token_id: path.token_id
          app_id: path.app_id
          ip_allowlist: requestBody.ip_allowlist
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/auth/tokens/{token_id}/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a compromised app API key
      effect: destructive
      questions:
      - What should I do if an app API key has leaked?
      - Can I get a fresh secret for a key without creating a new one from scratch?
      instructions:
      - text: Rotate API key {token_id} on app {app_id}.
        slots:
          token_id: path.token_id
          app_id: path.app_id
      - text: Issue a replacement secret for compromised key {token_id} in app {app_id}.
        slots:
          token_id: path.token_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/custom_events'].post
  update:
    x-apievangelist-phrasing:
      intent: Record custom user events
      effect: write
      questions:
      - How do I track purchases or milestones as custom events for my users?
      - Can custom events I send be used to trigger messaging?
      instructions:
      - text: Record custom events {events} for app {app_id}.
        slots:
          events: requestBody.events
          app_id: path.app_id
      - text: Log a completed purchase event {events} in app {app_id} through the custom_events endpoint.
        slots:
          events: requestBody.events
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/outcomes'].get
  update:
    x-apievangelist-phrasing:
      intent: View outcomes using the array-style outcome filter
      effect: read
      questions:
      - Can I pass several outcome names as an outcome_names[] array?
      - Why is my outcome data limited, and which API key does the outcomes report need?
      instructions:
      - text: Pull outcomes for app {app_id} with required outcome names {outcome_names}.
        slots:
          app_id: path.app_id
          outcome_names: query.outcome_names
      - text: Fetch outcomes {outcome_names} plus array values {outcome_names_array} for app {app_id}.
        slots:
          outcome_names: query.outcome_names
          outcome_names_array: query.outcome_names[]
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/notifications/{notification_id}/unsubscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe an email with a token (legacy endpoint)
      effect: write
      questions:
      - Is there an older endpoint for opting out an email via its unsubscribe token?
      - Which call does the legacy custom unsubscribe landing page use?
      instructions:
      - text: Use the legacy endpoint to unsubscribe token {token} from notification {notification_id} in app {app_id}.
        slots:
          token: query.token
          notification_id: path.notification_id
          app_id: path.app_id
      - text: Opt out email token {token} for notification {notification_id}, app {app_id}, via the older unsubscribe call.
        slots:
          token: query.token
          notification_id: path.notification_id
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app_id}/integrations/custom_events'].post
  update:
    x-apievangelist-phrasing:
      intent: Record custom events through the integrations path
      effect: write
      questions:
      - Is there an integrations endpoint for sending custom events from a partner tool?
      - Can an integration push user actions as custom events?
      instructions:
      - text: Send custom events {events} to app {app_id} via the integrations endpoint.
        slots:
          events: requestBody.events
          app_id: path.app_id
      - text: Push integration events {events} into app {app_id}.
        slots:
          events: requestBody.events
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'