# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Users.user Settings API
  version: 1.0.0
extends: openapi/azure-ad-users-usersettings-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: 50
- target: $.paths['/users/{user-id}/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's settings
      effect: read
      questions:
      - How do I see all of a user's settings, like content discovery and work hours, in one place?
      - Has this user opted out of contributing to content discovery?
      instructions:
      - text: Get the settings object for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show {user_id}'s top-level settings, expanding {expand}.
        slots:
          user_id: path.user-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's settings object
      effect: destructive
      questions:
      - Can I remove the whole settings object from a user account?
      - What wipes every stored setting for one user at once?
      instructions:
      - text: Delete the entire settings object for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Wipe all settings on {user_id} if the ETag is {etag}.
        slots:
          user_id: path.user-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's settings
      effect: write
      questions:
      - Can I stop a user's activity from feeding content discovery in Microsoft 365?
      - Which top-level user settings can I change in a single update?
      instructions:
      - text: Set contributionToContentDiscoveryDisabled to {disabled} for user {user_id}.
        slots:
          disabled: requestBody.contributionToContentDiscoveryDisabled
          user_id: path.user-id
      - text: Update the settings for {user_id} so content discovery as organization is disabled ({org_disabled}).
        slots:
          user_id: path.user-id
          org_disabled: requestBody.contributionToContentDiscoveryAsOrganizationDisabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/exchange'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's Exchange mailboxes
      effect: read
      questions:
      - Which Exchange mailboxes belong to a user, including shared ones?
      - Can I see a person's primary mailbox alongside the shared mailboxes they have?
      instructions:
      - text: List the Exchange mailboxes for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show the primary and shared mailboxes that {user_id} has.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/itemInsights'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's item insights privacy setting
      effect: read
      questions:
      - Is item insights turned on for this user?
      - Are meeting hour insights visible for a given person, or disabled?
      instructions:
      - text: Get the item insights privacy setting for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Tell me whether insights are enabled for {user_id}.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/itemInsights'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's item insights setting
      effect: destructive
      questions:
      - Can I remove the item insights settings object from someone's account?
      - What deletes a user's userInsightsSettings entirely?
      instructions:
      - text: Delete the item insights setting for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Remove {user_id}'s insights privacy object with ETag {etag}.
        slots:
          user_id: path.user-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/itemInsights'].patch
  update:
    x-apievangelist-phrasing:
      intent: Turn a user's item insights on or off
      effect: write
      questions:
      - How do I disable item and meeting hour insights for a privacy-sensitive user?
      - Can I re-enable insights for someone who had them switched off?
      instructions:
      - text: Set item insights isEnabled to {enabled} for user {user_id}.
        slots:
          enabled: requestBody.isEnabled
          user_id: path.user-id
      - text: Turn off item and meeting hour insights for {user_id}.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/shiftPreferences'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's shift availability preferences
      effect: read
      questions:
      - When is a shift worker available according to their shift preferences?
      - Can I read someone's stated availability for scheduling shifts?
      instructions:
      - text: Get the shift preferences for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show when {user_id} says they're available for shifts.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/shiftPreferences'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's shift preferences
      effect: destructive
      questions:
      - Can I clear a worker's saved shift availability?
      - What removes the shiftPreferences object for one user?
      instructions:
      - text: Delete the shift preferences for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Clear {user_id}'s shift availability with ETag {etag}.
        slots:
          user_id: path.user-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/shiftPreferences'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's shift availability
      effect: write
      questions:
      - How do I record that an employee is only available certain days for shifts?
      - Can I change a shift worker's availability windows?
      instructions:
      - text: Set the shift availability for user {user_id} to {availability}.
        slots:
          user_id: path.user-id
          availability: requestBody.availability
      - text: Update {user_id}'s shift preferences with availability {availability}.
        slots:
          user_id: path.user-id
          availability: requestBody.availability
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's storage settings
      effect: read
      questions:
      - Where can I see a user's storage settings, including their quota?
      - Can I read the storage settings object for one person?
      instructions:
      - text: Get the storage settings for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show {user_id}'s storage settings with the quota expanded via {expand}.
        slots:
          user_id: path.user-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's storage settings
      effect: destructive
      questions:
      - Can I remove the storage settings object from a user?
      - What deletes someone's storage settings node entirely?
      instructions:
      - text: Delete the storage settings for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Remove {user_id}'s storage settings if the ETag matches {etag}.
        slots:
          user_id: path.user-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's storage settings
      effect: write
      questions:
      - Can I replace the quota inside a user's storage settings?
      - Which storage setting fields are writable for a user?
      instructions:
      - text: Update the storage settings for user {user_id} with quota {quota}.
        slots:
          user_id: path.user-id
          quota: requestBody.quota
      - text: Patch {user_id}'s storage settings node.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a user's storage quota usage
      effect: read
      questions:
      - How much of their storage quota has a user used, and how much remains?
      - Is someone close to running out of Microsoft 365 storage?
      instructions:
      - text: Show the storage quota used, remaining and total for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Check whether {user_id}'s storage quota state is near full.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's storage quota record
      effect: destructive
      questions:
      - Can I remove the quota object from a user's storage settings?
      - What deletes someone's stored quota details?
      instructions:
      - text: Delete the storage quota record for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Remove the quota from {user_id}'s storage with ETag {etag}.
        slots:
          user_id: path.user-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's storage quota values
      effect: write
      questions:
      - Can I set the total or used figures on a user's storage quota record?
      - Which quota fields, like state or manage URL, are editable?
      instructions:
      - text: Set the storage quota total for user {user_id} to {total}.
        slots:
          user_id: path.user-id
          total: requestBody.total
      - text: Update {user_id}'s quota state to {state} and manage URL to {manage_url}.
        slots:
          user_id: path.user-id
          state: requestBody.state
          manage_url: requestBody.manageWebUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services'].get
  update:
    x-apievangelist-phrasing:
      intent: Break down a user's storage use by service
      effect: read
      questions:
      - Which services are using up a user's storage, like mail versus files?
      - Can I see a per-service breakdown of someone's quota consumption?
      instructions:
      - text: List the per-service storage breakdown for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show {user_id}'s storage by service sorted by {orderby}.
        slots:
          user_id: path.user-id
          orderby: query.$orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a service storage breakdown entry
      effect: write
      questions:
      - Can I add a new service entry to a user's storage quota breakdown?
      - What creates a serviceStorageQuotaBreakdown record for someone?
      instructions:
      - text: Create a new service storage breakdown entry for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Add a per-service quota record under {user_id}'s storage.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services/{serviceStorageQuotaBreakdown-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one service's storage use for a user
      effect: read
      questions:
      - How much storage does one specific service consume for a user?
      - Can I read a single entry from someone's per-service quota breakdown?
      instructions:
      - text: Get service breakdown {service_id} from user {user_id}'s storage quota.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      - text: Show how much storage service {service_id} uses for {user_id}.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services/{serviceStorageQuotaBreakdown-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a service storage breakdown entry
      effect: destructive
      questions:
      - Can I remove one service's line from a user's quota breakdown?
      - What deletes a specific serviceStorageQuotaBreakdown record?
      instructions:
      - text: Delete service breakdown {service_id} from user {user_id}'s quota.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      - text: Remove the {service_id} storage entry for {user_id}.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services/{serviceStorageQuotaBreakdown-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a service storage breakdown entry
      effect: write
      questions:
      - Can I edit one service's entry in a user's storage quota breakdown?
      - What changes an existing serviceStorageQuotaBreakdown record?
      instructions:
      - text: Update service breakdown {service_id} in user {user_id}'s quota.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      - text: Patch the {service_id} per-service storage record for {user_id}.
        slots:
          service_id: path.serviceStorageQuotaBreakdown-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/storage/quota/services/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count services in a user's storage breakdown
      effect: read
      questions:
      - How many services appear in a user's storage quota breakdown?
      - What's the count of per-service storage entries matching a filter?
      instructions:
      - text: Count the service storage entries for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Count {user_id}'s storage services where {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's cloud-stored Windows settings
      effect: read
      questions:
      - Which Windows settings does a user have backed up in the cloud?
      - Can I filter someone's roamed Windows settings by device?
      instructions:
      - text: List the Windows settings stored in the cloud for user {user_id}.
        slots:
          user_id: path.user-id
      - text: List {user_id}'s Windows settings matching {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a Windows setting for a user
      effect: write
      questions:
      - Can I store a new Windows setting for a user tied to a specific device?
      - What goes into a new windowsSetting, like its setting type and payload type?
      instructions:
      - text: Create a Windows setting of type {setting_type} for user {user_id} on device {device_id}.
        slots:
          setting_type: requestBody.settingType
          user_id: path.user-id
          device_id: requestBody.windowsDeviceId
      - text: Add a Windows setting for {user_id} with payload type {payload_type}.
        slots:
          user_id: path.user-id
          payload_type: requestBody.payloadType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of a user's Windows settings
      effect: read
      questions:
      - What device and setting type does a particular cloud Windows setting belong to?
      - Can I read a single windowsSetting by its id?
      instructions:
      - text: Get Windows setting {setting_id} for user {user_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Show the details of {user_id}'s Windows setting {setting_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of a user's Windows settings
      effect: destructive
      questions:
      - Can I delete a Windows setting a user has roamed to the cloud?
      - What removes a single windowsSetting from someone's account?
      instructions:
      - text: Delete Windows setting {setting_id} for user {user_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Remove cloud Windows setting {setting_id} from {user_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one of a user's Windows settings
      effect: write
      questions:
      - Can I reassign a stored Windows setting to a different device id?
      - Which fields of an existing windowsSetting can be changed?
      instructions:
      - text: Set the device on Windows setting {setting_id} for user {user_id} to {device_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
          device_id: requestBody.windowsDeviceId
      - text: Change the setting type of {user_id}'s Windows setting {setting_id} to {setting_type}.
        slots:
          user_id: path.user-id
          setting_id: path.windowsSetting-id
          setting_type: requestBody.settingType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances'].get
  update:
    x-apievangelist-phrasing:
      intent: List values stored for a Windows setting
      effect: read
      questions:
      - Which setting values are stored under one of a user's Windows settings?
      - Can I see when each instance of a Windows setting expires?
      instructions:
      - text: List the instances of Windows setting {setting_id} for user {user_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Show the stored values under {user_id}'s Windows setting {setting_id} sorted by {orderby}.
        slots:
          user_id: path.user-id
          setting_id: path.windowsSetting-id
          orderby: query.$orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a value to a Windows setting
      effect: write
      questions:
      - Can I store a new setting value with an expiration under a user's Windows setting?
      - What does a new windowsSettingInstance need, such as its payload?
      instructions:
      - text: Add an instance with payload {payload} to Windows setting {setting_id} for user {user_id}.
        slots:
          payload: requestBody.payload
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Create a value under {user_id}'s Windows setting {setting_id} that expires at {expires}.
        slots:
          user_id: path.user-id
          setting_id: path.windowsSetting-id
          expires: requestBody.expirationDateTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances/{windowsSettingInstance-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one value of a Windows setting
      effect: read
      questions:
      - What payload does a single instance of a user's Windows setting hold?
      - When was one specific Windows setting value last modified?
      instructions:
      - text: Get instance {instance_id} of Windows setting {setting_id} for user {user_id}.
        slots:
          instance_id: path.windowsSettingInstance-id
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Show the payload of value {instance_id} in {user_id}'s Windows setting {setting_id}.
        slots:
          instance_id: path.windowsSettingInstance-id
          user_id: path.user-id
          setting_id: path.windowsSetting-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances/{windowsSettingInstance-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one value of a Windows setting
      effect: destructive
      questions:
      - Can I remove a single stored value from a user's Windows setting?
      - What deletes one windowsSettingInstance by id?
      instructions:
      - text: Delete instance {instance_id} from Windows setting {setting_id} for user {user_id}.
        slots:
          instance_id: path.windowsSettingInstance-id
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Remove value {instance_id} under {user_id}'s Windows setting {setting_id}.
        slots:
          instance_id: path.windowsSettingInstance-id
          user_id: path.user-id
          setting_id: path.windowsSetting-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances/{windowsSettingInstance-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one value of a Windows setting
      effect: write
      questions:
      - Can I change the payload of an existing Windows setting value?
      - How would I push out the expiration on one stored Windows setting instance?
      instructions:
      - text: Set the payload of instance {instance_id} in Windows setting {setting_id} for user {user_id} to {payload}.
        slots:
          instance_id: path.windowsSettingInstance-id
          setting_id: path.windowsSetting-id
          user_id: path.user-id
          payload: requestBody.payload
      - text: Extend value {instance_id} of {user_id}'s Windows setting {setting_id} to expire at {expires}.
        slots:
          instance_id: path.windowsSettingInstance-id
          user_id: path.user-id
          setting_id: path.windowsSetting-id
          expires: requestBody.expirationDateTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/{windowsSetting-id}/instances/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count values stored for a Windows setting
      effect: read
      questions:
      - How many values are stored under one of a user's Windows settings?
      - What's the number of Windows setting instances that match a filter?
      instructions:
      - text: Count the instances of Windows setting {setting_id} for user {user_id}.
        slots:
          setting_id: path.windowsSetting-id
          user_id: path.user-id
      - text: Count values in {user_id}'s Windows setting {setting_id} where {filter}.
        slots:
          user_id: path.user-id
          setting_id: path.windowsSetting-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/windows/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's cloud-stored Windows settings
      effect: read
      questions:
      - How many Windows settings does a user have stored in the cloud?
      - What's the count of someone's Windows settings for one device?
      instructions:
      - text: Count the Windows settings for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Count {user_id}'s Windows settings where {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's work hours and location settings
      effect: read
      questions:
      - What are a user's work hours and location preferences for scheduling?
      - Can I see how much of someone's work location detail they share with others?
      instructions:
      - text: Get the work hours and location settings for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show {user_id}'s work plan settings with {expand} expanded.
        slots:
          user_id: path.user-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's work hours and location settings
      effect: write
      questions:
      - Can I limit how much work location detail a user shares with colleagues?
      - Which work hours and location settings can be changed in one update?
      instructions:
      - text: Set maxSharedWorkLocationDetails to {max_shared} for user {user_id}.
        slots:
          max_shared: requestBody.maxSharedWorkLocationDetails
          user_id: path.user-id
      - text: Update the work hours and location settings for {user_id}.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/microsoft.graph.occurrencesView(startDateTime=\'{startDateTime}\',endDateTime=\'{endDateTime}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: View work plan occurrences in a date range
      effect: read
      questions:
      - Where is a user planning to work between two dates?
      - Can I get someone's work plan for next week only, with start and end dates?
      instructions:
      - text: Show the work plan for user {user_id} from {start} to {end}.
        slots:
          user_id: path.user-id
          start: path.startDateTime
          end: path.endDateTime
      - text: Get {user_id}'s work location occurrences between {start} and {end}, top {top}.
        slots:
          user_id: path.user-id
          start: path.startDateTime
          end: path.endDateTime
          top: query.$top
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences'].get
  update:
    x-apievangelist-phrasing:
      intent: List all of a user's work plan occurrences
      effect: read
      questions:
      - Which work plan occurrences, like office days and time off, does a user have?
      - Can I list every work plan occurrence with a filter instead of a date window?
      instructions:
      - text: List all work plan occurrences for user {user_id}.
        slots:
          user_id: path.user-id
      - text: List {user_id}'s work plan occurrences matching {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a one-off work plan occurrence
      effect: write
      questions:
      - How do I record that someone will work from the office on one particular day?
      - Can I add a single time-off block to a user's work plan?
      instructions:
      - text: Add a work plan occurrence for user {user_id} from {start} to {end} at location type {location_type}.
        slots:
          user_id: path.user-id
          start: requestBody.start
          end: requestBody.end
          location_type: requestBody.workLocationType
      - text: Create a time-off occurrence for {user_id} from {start} to {end} with details {time_off}.
        slots:
          user_id: path.user-id
          start: requestBody.start
          end: requestBody.end
          time_off: requestBody.timeOffDetails
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences/{workPlanOccurrence-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one work plan occurrence
      effect: read
      questions:
      - What location and times does a specific work plan occurrence cover?
      - Can I look up one occurrence from a user's work plan by id?
      instructions:
      - text: Get work plan occurrence {occurrence_id} for user {user_id}.
        slots:
          occurrence_id: path.workPlanOccurrence-id
          user_id: path.user-id
      - text: Show where {user_id} works during occurrence {occurrence_id}.
        slots:
          user_id: path.user-id
          occurrence_id: path.workPlanOccurrence-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences/{workPlanOccurrence-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a work plan occurrence
      effect: write
      questions:
      - Can I change the place or hours on an existing work plan occurrence?
      - What replaces a single day's entry in someone's work plan?
      instructions:
      - text: Replace work plan occurrence {occurrence_id} for user {user_id} with start {start} and end {end}.
        slots:
          occurrence_id: path.workPlanOccurrence-id
          user_id: path.user-id
          start: requestBody.start
          end: requestBody.end
      - text: Move {user_id}'s occurrence {occurrence_id} to place {place_id}.
        slots:
          user_id: path.user-id
          occurrence_id: path.workPlanOccurrence-id
          place_id: requestBody.placeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences/{workPlanOccurrence-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a work plan occurrence
      effect: destructive
      questions:
      - Can I remove one day's entry from a user's work plan?
      - What cancels a single scheduled work plan occurrence?
      instructions:
      - text: Delete work plan occurrence {occurrence_id} for user {user_id}.
        slots:
          occurrence_id: path.workPlanOccurrence-id
          user_id: path.user-id
      - text: Remove occurrence {occurrence_id} from {user_id}'s work plan.
        slots:
          occurrence_id: path.workPlanOccurrence-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's work plan occurrences
      effect: read
      questions:
      - How many work plan occurrences does a user have scheduled?
      - What's the number of someone's occurrences that match a filter?
      instructions:
      - text: Count the work plan occurrences for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Count {user_id}'s work plan occurrences where {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/occurrences/microsoft.graph.setCurrentLocation'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a user's work location for today
      effect: write
      questions:
      - How do I quickly mark that I'm working remotely today without editing my work plan?
      - Can I update just the current segment's work location instead of the whole day?
      instructions:
      - text: Set today's work location for user {user_id} to {location_type}.
        slots:
          user_id: path.user-id
          location_type: requestBody.workLocationType
      - text: Change {user_id}'s current work location to place {place_id} for scope {update_scope}.
        slots:
          user_id: path.user-id
          place_id: requestBody.placeId
          update_scope: requestBody.updateScope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's recurring work plans
      effect: read
      questions:
      - Which recurring weekly work patterns has a user defined?
      - Does this person have a standing office day every week?
      instructions:
      - text: List the recurring work plans for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Show {user_id}'s repeating work schedules matching {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a recurring work plan
      effect: write
      questions:
      - How do I set up a repeating schedule, like office every Tuesday, for a user?
      - Can I create a recurring remote-work pattern with a location type?
      instructions:
      - text: Create a recurring work plan for user {user_id} with pattern {recurrence} at location type {location_type}.
        slots:
          user_id: path.user-id
          recurrence: requestBody.recurrence
          location_type: requestBody.workLocationType
      - text: Add a repeating schedule for {user_id} from {start} to {end} following {recurrence}.
        slots:
          user_id: path.user-id
          start: requestBody.start
          end: requestBody.end
          recurrence: requestBody.recurrence
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences/{workPlanRecurrence-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one recurring work plan
      effect: read
      questions:
      - What pattern and location does a particular recurring work plan follow?
      - Can I read one of a user's repeating schedules by id?
      instructions:
      - text: Get recurring work plan {recurrence_id} for user {user_id}.
        slots:
          recurrence_id: path.workPlanRecurrence-id
          user_id: path.user-id
      - text: Show the repeat pattern of {user_id}'s recurrence {recurrence_id}.
        slots:
          user_id: path.user-id
          recurrence_id: path.workPlanRecurrence-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences/{workPlanRecurrence-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a recurring work plan
      effect: write
      questions:
      - Can I change the repeat pattern of an existing recurring work plan?
      - What replaces a standing weekly schedule with a new location?
      instructions:
      - text: Replace recurring work plan {recurrence_id} for user {user_id} with pattern {recurrence}.
        slots:
          recurrence_id: path.workPlanRecurrence-id
          user_id: path.user-id
          recurrence: requestBody.recurrence
      - text: Switch {user_id}'s recurrence {recurrence_id} to location type {location_type}.
        slots:
          user_id: path.user-id
          recurrence_id: path.workPlanRecurrence-id
          location_type: requestBody.workLocationType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences/{workPlanRecurrence-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a recurring work plan
      effect: destructive
      questions:
      - Can I stop a repeating work schedule by deleting it?
      - What removes one recurring work plan from a user?
      instructions:
      - text: Delete recurring work plan {recurrence_id} for user {user_id}.
        slots:
          recurrence_id: path.workPlanRecurrence-id
          user_id: path.user-id
      - text: Remove the repeating schedule {recurrence_id} from {user_id}.
        slots:
          recurrence_id: path.workPlanRecurrence-id
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}/settings/workHoursAndLocations/recurrences/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a user's recurring work plans
      effect: read
      questions:
      - How many recurring work plans does a user have?
      - What's the count of someone's repeating schedules matching a filter?
      instructions:
      - text: Count the recurring work plans for user {user_id}.
        slots:
          user_id: path.user-id
      - text: Count {user_id}'s recurring work plans where {filter}.
        slots:
          user_id: path.user-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'