# 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 Subscriptions API
  version: 1.0.0
extends: openapi/knock-app-subscriptions-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: 4
- target: $.paths['/v1/objects/{collection}/{object_id}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an object's subscriptions
      effect: read
      questions:
      - Who is subscribed to a given object, like a project or channel?
      - Can I list the objects an object itself subscribes to?
      instructions:
      - text: List subscribers of object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
      - text: List {collection}/{object_id} subscriptions in mode {mode}.
        slots:
          object_id: path.object_id
          collection: path.collection
          mode: query.mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe recipients to an object
      effect: write
      questions:
      - How do I subscribe users to an object so they get its notifications?
      - Can I attach custom properties to a subscription?
      instructions:
      - text: Subscribe {recipients} to object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
          recipients: requestBody.recipients
      - text: Add {recipients} as subscribers of {collection}/{object_id} with properties {properties}.
        slots:
          object_id: path.object_id
          collection: path.collection
          recipients: requestBody.recipients
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/subscriptions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe recipients from an object
      effect: destructive
      questions:
      - How do I unsubscribe users from an object?
      - Does removing subscriptions return what was deleted?
      instructions:
      - text: Unsubscribe {recipients} from object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
          recipients: requestBody.recipients
      - text: Remove {recipients}' subscriptions to {collection}/{object_id}.
        slots:
          object_id: path.object_id
          collection: path.collection
          recipients: requestBody.recipients
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's subscriptions
      effect: read
      questions:
      - Which objects is a particular user subscribed to?
      - Can I check whether a user subscribes to specific objects?
      instructions:
      - text: List subscriptions for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show whether user {user_id} subscribes to {objects}.
        slots:
          user_id: path.user_id
          objects: query.objects[]
      method: generated
      generated: '2026-10-01'