# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canvas LMS REST Content Shares API
  version: 1.0.0
extends: openapi/canvas-content-shares-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: 8
- target: $.paths['/v1/users/{user_id}/content_shares'].post
  update:
    x-apievangelist-phrasing:
      intent: Share content directly with other users
      effect: write
      questions:
      - How do I share a quiz or page directly with another teacher?
      - Can I send one piece of course content to several users at once?
      instructions:
      - text: Share {content_type} {content_id} from user {user_id} with {receiver_ids}.
        slots:
          content_type: requestBody.content_type
          content_id: requestBody.content_id
          user_id: path.user_id
          receiver_ids: requestBody.receiver_ids
      - text: Send my {content_type} {content_id} to users {receiver_ids}.
        slots:
          content_type: requestBody.content_type
          content_id: requestBody.content_id
          receiver_ids: requestBody.receiver_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/sent'].get
  update:
    x-apievangelist-phrasing:
      intent: List content shares a user has sent
      effect: read
      questions:
      - What content have I shared with other people?
      - Can an observer see the content shares a linked student has sent?
      instructions:
      - text: List the content shares user {user_id} has sent.
        slots:
          user_id: path.user_id
      - text: Show everything I've shared out with others.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/received'].get
  update:
    x-apievangelist-phrasing:
      intent: List content shares a user has received
      effect: read
      questions:
      - What content have other people shared with me?
      - How do I see the content shares a user has received?
      instructions:
      - text: List the content shares user {user_id} has received.
        slots:
          user_id: path.user_id
      - text: Show the content others have shared with me.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/unread_count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count unread received content shares
      effect: read
      questions:
      - How many shared items haven't I opened yet?
      - What's the unread content share count for a user?
      instructions:
      - text: Count unread content shares for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Tell me how many shared items I haven't read.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single content share
      effect: read
      questions:
      - How do I see the details of one content share?
      - Who sent a particular shared item and what content does it contain?
      instructions:
      - text: Get content share {id} for user {user_id}.
        slots:
          id: path.id
          user_id: path.user_id
      - text: Show the details of my content share {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a content share read or unread
      effect: write
      questions:
      - How do I mark a shared item as read?
      - Can I flip a content share back to unread?
      instructions:
      - text: Mark content share {id} for user {user_id} as {read_state}.
        slots:
          id: path.id
          user_id: path.user_id
          read_state: requestBody.read_state
      - text: Mark my content share {id} as read.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a content share from my list
      effect: destructive
      questions:
      - How do I remove a shared item from my list?
      - Does removing a content share delete other people's copies?
      instructions:
      - text: Remove content share {id} from user {user_id}'s list.
        slots:
          id: path.id
          user_id: path.user_id
      - text: Delete content share {id} from my shares.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/content_shares/{id}/add_users'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an existing content share to more users
      effect: write
      questions:
      - How do I send something I already shared to additional people?
      - Can I add recipients to a content share after creating it?
      instructions:
      - text: Add users {receiver_ids} to content share {id} from user {user_id}.
        slots:
          receiver_ids: requestBody.receiver_ids
          id: path.id
          user_id: path.user_id
      - text: Also send my content share {id} to {receiver_ids}.
        slots:
          id: path.id
          receiver_ids: requestBody.receiver_ids
      method: generated
      generated: '2026-10-01'