# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluence Cloud REST Content watches API
  version: 1.0.0
extends: openapi/confluence-content-watches-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: 12
- target: $.paths['/wiki/rest/api/content/{id}/notification/child-created'].get
  update:
    x-apievangelist-phrasing:
      intent: List who is watching a page
      effect: read
      questions:
      - Who gets notified when a particular Confluence page is updated?
      - Can I page through the list of a page's watchers?
      instructions:
      - text: List the watchers of page {id}.
        slots:
          id: path.id
      - text: Show {limit} page watchers for page {id} starting at {start}.
        slots:
          limit: query.limit
          id: path.id
          start: query.start
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/content/{id}/notification/created'].get
  update:
    x-apievangelist-phrasing:
      intent: List space watches for the space a page is in
      effect: read
      questions:
      - Starting from a page, how do I find who watches the space it lives in?
      - Which space-level watches cover the space that holds a given piece of content?
      instructions:
      - text: List the space watches for the space containing content {id}.
        slots:
          id: path.id
      - text: Find who watches the whole space that page {id} belongs to.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/space/{spaceKey}/watch'].get
  update:
    x-apievangelist-phrasing:
      intent: List the watchers of a space by key
      effect: read
      questions:
      - Who is watching a space when I know its space key?
      - Can I list space watchers in batches with start and limit?
      instructions:
      - text: List the watchers of space {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      - text: Get the first {limit} watchers of space {spaceKey}.
        slots:
          limit: query.limit
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/content/{contentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user watches a piece of content
      effect: read
      questions:
      - Am I watching a specific page right now?
      - Can I check whether a colleague is watching a page by their account ID?
      instructions:
      - text: Check whether I am watching content {contentId}.
        slots:
          contentId: path.contentId
      - text: Tell me if user {accountId} watches content {contentId}.
        slots:
          accountId: query.accountId
          contentId: path.contentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/content/{contentId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Start watching a piece of content
      effect: write
      questions:
      - How do I subscribe to updates on a single Confluence page?
      - Can I add another user as a watcher on a page?
      instructions:
      - text: Watch content {contentId} for me.
        slots:
          contentId: path.contentId
      - text: Add user {accountId} as a watcher of content {contentId}.
        slots:
          accountId: query.accountId
          contentId: path.contentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/content/{contentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a piece of content
      effect: destructive
      questions:
      - How do I stop getting notifications for one page?
      - Can I remove someone else from a page's watchers?
      instructions:
      - text: Unwatch content {contentId} for me.
        slots:
          contentId: path.contentId
      - text: Remove user {accountId} as a watcher of content {contentId}.
        slots:
          accountId: query.accountId
          contentId: path.contentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/label/{labelName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user watches a label
      effect: read
      questions:
      - Am I following a particular label?
      - Does a given user watch a label by account ID?
      instructions:
      - text: Check whether I'm watching label {labelName}.
        slots:
          labelName: path.labelName
      - text: Tell me if user {accountId} watches label {labelName}.
        slots:
          accountId: query.accountId
          labelName: path.labelName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/label/{labelName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Start watching a label
      effect: write
      questions:
      - How do I get notified about content tagged with a certain label?
      - Can I subscribe a teammate to a label?
      instructions:
      - text: Watch label {labelName} for me.
        slots:
          labelName: path.labelName
      - text: Add user {accountId} as a watcher of label {labelName}.
        slots:
          accountId: query.accountId
          labelName: path.labelName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/label/{labelName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a label
      effect: destructive
      questions:
      - How do I unfollow a label I'm watching?
      - Can I take a user off a label's watch list?
      instructions:
      - text: Unwatch label {labelName} for me.
        slots:
          labelName: path.labelName
      - text: Remove user {accountId} as a watcher of label {labelName}.
        slots:
          accountId: query.accountId
          labelName: path.labelName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/space/{spaceKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user watches a space
      effect: read
      questions:
      - Am I watching a particular space?
      - Is a specific user subscribed to a space's updates?
      instructions:
      - text: Check whether I'm watching space {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      - text: Tell me if user {accountId} watches space {spaceKey}.
        slots:
          accountId: query.accountId
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/space/{spaceKey}'].post
  update:
    x-apievangelist-phrasing:
      intent: Start watching a space
      effect: write
      questions:
      - How do I follow everything that changes in a Confluence space?
      - Can I subscribe another user to a whole space?
      instructions:
      - text: Watch space {spaceKey} for me.
        slots:
          spaceKey: path.spaceKey
      - text: Add user {accountId} as a watcher of space {spaceKey}.
        slots:
          accountId: query.accountId
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/watch/space/{spaceKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a space
      effect: destructive
      questions:
      - How do I stop space-wide notifications?
      - Can I unsubscribe a user from a space they're watching?
      instructions:
      - text: Unwatch space {spaceKey} for me.
        slots:
          spaceKey: path.spaceKey
      - text: Remove user {accountId} as a watcher of space {spaceKey}.
        slots:
          accountId: query.accountId
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'