# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio - Events Subscriptions API
  version: 1.0.0
extends: openapi/twilio-subscriptions-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: 10
- target: $.paths['/v1/Subscriptions/{SubscriptionSid}/SubscribedEvents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the event types in a subscription
      effect: read
      questions:
      - Which event types is one of my Event Streams subscriptions receiving?
      - Can I see every event type a subscription is signed up for, with its schema version?
      instructions:
      - text: List the event types subscribed on subscription {subscription}.
        slots:
          subscription: path.SubscriptionSid
      - text: Show all subscribed events for {subscription}, {page_size} per page.
        slots:
          subscription: path.SubscriptionSid
          page_size: query.PageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{SubscriptionSid}/SubscribedEvents'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an event type to a subscription
      effect: write
      questions:
      - How do I start receiving one more event type on a subscription I already have?
      - Can I pick the schema version when adding an event type to a subscription?
      instructions:
      - text: Add event type {type} to subscription {subscription}.
        slots:
          type: requestBody.Type
          subscription: path.SubscriptionSid
      - text: Subscribe {subscription} to {type} events using schema version {schema_version}.
        slots:
          subscription: path.SubscriptionSid
          type: requestBody.Type
          schema_version: requestBody.SchemaVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{SubscriptionSid}/SubscribedEvents/{Type}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one event type on a subscription
      effect: read
      questions:
      - Is a particular event type included in my subscription, and on which schema version?
      - What schema version does a subscribed event type currently use?
      instructions:
      - text: Show event type {type} on subscription {subscription}.
        slots:
          type: path.Type
          subscription: path.SubscriptionSid
      - text: Tell me the schema version subscription {subscription} uses for {type}.
        slots:
          subscription: path.SubscriptionSid
          type: path.Type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{SubscriptionSid}/SubscribedEvents/{Type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a subscribed event's schema version
      effect: write
      questions:
      - Can I move an event type I'm already subscribed to onto a newer schema version?
      - How do I upgrade the payload schema for one subscribed event type?
      instructions:
      - text: Switch event type {type} on subscription {subscription} to schema version {schema_version}.
        slots:
          type: path.Type
          subscription: path.SubscriptionSid
          schema_version: requestBody.SchemaVersion
      - text: Upgrade the already-subscribed {type} events in {subscription} to schema {schema_version}.
        slots:
          type: path.Type
          subscription: path.SubscriptionSid
          schema_version: requestBody.SchemaVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{SubscriptionSid}/SubscribedEvents/{Type}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an event type from a subscription
      effect: destructive
      questions:
      - How do I stop getting one event type without deleting the whole subscription?
      - Can I unsubscribe from a single noisy event type?
      instructions:
      - text: Remove event type {type} from subscription {subscription}.
        slots:
          type: path.Type
          subscription: path.SubscriptionSid
      - text: Stop sending {type} events on {subscription}.
        slots:
          type: path.Type
          subscription: path.SubscriptionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List my event subscriptions
      effect: read
      questions:
      - What Event Streams subscriptions exist on my Twilio account?
      - Which subscriptions are sending events to a particular sink?
      instructions:
      - text: List all my event subscriptions.
      - text: Show the subscriptions that deliver to sink {sink}.
        slots:
          sink: query.SinkSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an event subscription
      effect: write
      questions:
      - How do I route selected account events to a sink I've set up?
      - Does the sink need to be active before I create a subscription for it?
      instructions:
      - text: Create a subscription {description} sending {types} events to sink {sink}.
        slots:
          description: requestBody.Description
          types: requestBody.Types
          sink: requestBody.SinkSid
      - text: Start streaming event types {types} into sink {sink}, described as {description}.
        slots:
          types: requestBody.Types
          sink: requestBody.SinkSid
          description: requestBody.Description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an event subscription
      effect: read
      questions:
      - How can I see which sink one of my subscriptions points at?
      - Can I pull the details of a single event subscription by its SID?
      instructions:
      - text: Show event subscription {subscription}.
        slots:
          subscription: path.Sid
      - text: Tell me the sink and description of subscription {subscription}.
        slots:
          subscription: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a subscription's sink or description
      effect: write
      questions:
      - Can I redirect an existing subscription to a different sink?
      - How do I rename the description on a subscription I already created?
      instructions:
      - text: Point subscription {subscription} at sink {sink}.
        slots:
          subscription: path.Sid
          sink: requestBody.SinkSid
      - text: Change the description of subscription {subscription} to {description}.
        slots:
          subscription: path.Sid
          description: requestBody.Description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Subscriptions/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an event subscription
      effect: destructive
      questions:
      - How do I stop all events flowing through a subscription at once?
      - Can I delete an entire subscription with all its event types?
      instructions:
      - text: Delete event subscription {subscription}.
        slots:
          subscription: path.Sid
      - text: Tear down subscription {subscription} and everything it streams.
        slots:
          subscription: path.Sid
      method: generated
      generated: '2026-09-26'