API Evangelist conversational phrasing for Users.item Insights API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Users.item Insights API
  version: 1.0.0
extends: openapi/azure-ad-users-iteminsights-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: 25
- target: $.paths['/users/{user-id}/insights'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's item insights
      effect: read
      questions:
      - How do I see the document insights Microsoft Graph has calculated for a user?
      - Can I pull a user's shared, trending and used documents together in one response?
      instructions:
      - text: Get the item insights container for user {user}.
        slots:
          user: path.user-id
      - text: Show insights for user {user} and expand {relationship}.
        slots:
          user: path.user-id
          relationship: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's item insights
      effect: destructive
      questions:
      - Can I wipe the calculated document insights for a user?
      - What removes the whole insights object from a user rather than one item?
      instructions:
      - text: Delete the item insights for user {user}.
        slots:
          user: path.user-id
      - text: Remove the entire insights container from user {user}.
        slots:
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's item insights container
      effect: write
      questions:
      - Is there a patch call for a user's top-level insights object?
      - Can I update the insights container on a user account?
      instructions:
      - text: Update the insights container for user {user}.
        slots:
          user: path.user-id
      - text: Patch the top-level item insights object on user {user}.
        slots:
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents shared with or by a user
      effect: read
      questions:
      - Which files have been shared with or by a particular user recently?
      - Can I filter a user's shared-document insights to one kind of attachment?
      instructions:
      - text: List the documents shared with or by user {user}.
        slots:
          user: path.user-id
      - text: List the {count} most recent shared-document insights for user {user}.
        slots:
          count: query.$top
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a shared-document insight for a user
      effect: write
      questions:
      - Can I add a shared insight record to a user's insights?
      - Is it possible to create a shared-item entry with its sharing history?
      instructions:
      - text: Create a shared insight for user {user} pointing at {resourceReference}.
        slots:
          user: path.user-id
          resourceReference: requestBody.resourceReference
      - text: Add a shared-document insight for user {user} with sharing history {history}.
        slots:
          user: path.user-id
          history: requestBody.sharingHistory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/{sharedInsight-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one shared-document insight
      effect: read
      questions:
      - What details are stored for one specific shared-document insight?
      - When was a particular shared file last shared with the user?
      instructions:
      - text: Get shared insight {insight} for user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      - text: Show when shared item {insight} was last shared with user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/{sharedInsight-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shared-document insight
      effect: destructive
      questions:
      - Can I remove one shared-document insight from a user's list?
      - How would I delete a single shared item record from a user's insights?
      instructions:
      - text: Delete shared insight {insight} from user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      - text: Remove shared-document record {insight} for user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/{sharedInsight-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a shared-document insight
      effect: write
      questions:
      - Can I change the visualization details on an existing shared insight?
      - Is a shared insight's sharing history editable after it exists?
      instructions:
      - text: Update the resource visualization of shared insight {insight} for user {user} to {visualization}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
          visualization: requestBody.resourceVisualization
      - text: Patch the sharing history on shared insight {insight} of user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/{sharedInsight-id}/lastSharedMethod'].get
  update:
    x-apievangelist-phrasing:
      intent: See how a shared document was last shared
      effect: read
      questions:
      - How was a shared file most recently sent to the user, by email or another route?
      - Where do I find the last sharing method for a shared-document insight?
      instructions:
      - text: Get the last shared method for shared insight {insight} of user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      - text: Show the item that carried the most recent share of {insight} to user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/{sharedInsight-id}/resource'].get
  update:
    x-apievangelist-phrasing:
      intent: Open the item behind a shared insight
      effect: read
      questions:
      - How do I navigate from a shared insight to the actual file or attachment?
      - Is the resource behind a shared insight a file attachment or a drive item?
      instructions:
      - text: Get the underlying shared item for shared insight {insight} of user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      - text: Open the file that shared insight {insight} refers to for user {user}.
        slots:
          insight: path.sharedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/shared/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's shared-document insights
      effect: read
      questions:
      - How many documents have been shared with or by a given user?
      - Can I count only the shared insights that match a filter?
      instructions:
      - text: Count the shared-document insights for user {user}.
        slots:
          user: path.user-id
      - text: Count user {user}'s shared insights matching {filter}.
        slots:
          user: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents trending around a user
      effect: read
      questions:
      - What documents are trending among the people a user works with most closely?
      - Can I sort a user's trending documents by weight?
      instructions:
      - text: List trending documents for user {user}.
        slots:
          user: path.user-id
      - text: List trending documents for user {user} ordered by {order}.
        slots:
          user: path.user-id
          order: query.$orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a trending-document insight for a user
      effect: write
      questions:
      - Can I add a trending item to a user's insights with a relevance weight?
      - Is it possible to create a trending-document entry manually?
      instructions:
      - text: Create a trending insight for user {user} with weight {weight}.
        slots:
          user: path.user-id
          weight: requestBody.weight
      - text: Add a trending-document entry for user {user} referencing {resourceReference}.
        slots:
          user: path.user-id
          resourceReference: requestBody.resourceReference
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending/{trending-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one trending-document insight
      effect: read
      questions:
      - How strongly is a specific document trending for a user?
      - What does a single trending insight record contain?
      instructions:
      - text: Get trending insight {trending} for user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      - text: Show the weight and last-modified time of trending item {trending} for user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending/{trending-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a trending-document insight
      effect: destructive
      questions:
      - Can I remove a document from a user's trending insights?
      - How do I delete a single trending record for a user?
      instructions:
      - text: Delete trending insight {trending} from user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      - text: Remove trending document {trending} from user {user}'s insights.
        slots:
          trending: path.trending-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending/{trending-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a trending-document insight
      effect: write
      questions:
      - Can I adjust the weight on an existing trending insight?
      - Is the last-modified time of a trending record editable?
      instructions:
      - text: Set the weight of trending insight {trending} for user {user} to {weight}.
        slots:
          trending: path.trending-id
          user: path.user-id
          weight: requestBody.weight
      - text: Update the resource visualization on trending item {trending} for user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending/{trending-id}/resource'].get
  update:
    x-apievangelist-phrasing:
      intent: Open the document behind a trending insight
      effect: read
      questions:
      - How do I get to the actual document that a trending insight points at?
      - What item is behind a given trending record?
      instructions:
      - text: Get the trending document behind insight {trending} for user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      - text: Open the file that trending item {trending} refers to for user {user}.
        slots:
          trending: path.trending-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/trending/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's trending-document insights
      effect: read
      questions:
      - How many documents are trending around a particular user?
      - Can I count trending insights that match a filter?
      instructions:
      - text: Count trending documents for user {user}.
        slots:
          user: path.user-id
      - text: Count user {user}'s trending insights matching {filter}.
        slots:
          user: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents a user recently viewed or edited
      effect: read
      questions:
      - Which OneDrive and SharePoint documents has a user opened or modified lately?
      - Can I see a user's recently used files ordered by last access?
      instructions:
      - text: List the documents user {user} recently viewed or modified.
        slots:
          user: path.user-id
      - text: List used-document insights for user {user} filtered by {filter}.
        slots:
          user: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a used-document insight for a user
      effect: write
      questions:
      - Can I add a recently-used document record to a user's insights?
      - Is it possible to create a used insight with its last-used details?
      instructions:
      - text: Create a used insight for user {user} with last-used info {lastUsed}.
        slots:
          user: path.user-id
          lastUsed: requestBody.lastUsed
      - text: Add a recently used document entry for user {user} referencing {resourceReference}.
        slots:
          user: path.user-id
          resourceReference: requestBody.resourceReference
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used/{usedInsight-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one used-document insight
      effect: read
      questions:
      - When did a user last access a specific document in their used insights?
      - What details does a single used insight record hold?
      instructions:
      - text: Get used insight {used} for user {user}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      - text: Show when user {user} last accessed used item {used}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used/{usedInsight-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a used-document insight
      effect: destructive
      questions:
      - Can I remove a document from a user's recently used insights?
      - How do I delete a single used-document record?
      instructions:
      - text: Delete used insight {used} from user {user}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      - text: Remove recently used document {used} from user {user}'s insights.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used/{usedInsight-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a used-document insight
      effect: write
      questions:
      - Can I change the last-used details on an existing used insight?
      - Is a used insight's visualization editable?
      instructions:
      - text: Update last-used info on used insight {used} for user {user} to {lastUsed}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
          lastUsed: requestBody.lastUsed
      - text: Patch the resource visualization of used item {used} for user {user}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used/{usedInsight-id}/resource'].get
  update:
    x-apievangelist-phrasing:
      intent: Open the item behind a used insight
      effect: read
      questions:
      - How do I navigate from a used insight to the file the user actually worked on?
      - Is the item behind a used insight a drive item or an attachment?
      instructions:
      - text: Get the underlying item for used insight {used} of user {user}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      - text: Open the document that used record {used} refers to for user {user}.
        slots:
          used: path.usedInsight-id
          user: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/insights/used/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's used-document insights
      effect: read
      questions:
      - How many documents has a user recently viewed or modified?
      - Can I count used insights that match a filter?
      instructions:
      - text: Count the used-document insights for user {user}.
        slots:
          user: path.user-id
      - text: Count user {user}'s used insights matching {filter}.
        slots:
          user: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'