Microsoft Entra ID (formerly Azure AD) · OpenAPI Overlay 1.0.0
API Evangelist conversational phrasing for Users.profile Photo API
12 actions
12 updates
phrasing
extends
openapi/azure-ad-users-profilephoto-api-openapi.yml
Generated by API Evangelist
Written by API Evangelist tooling for Microsoft Entra ID (formerly Azure AD)'s API. It is a proposal applied on top of the contract, not a document Microsoft Entra ID (formerly Azure AD) publishes.
What the actions change
x-apievangelist-phrasing
Targets 12
$.info
$.paths['/users/{user-id}/photo'].get
$.paths['/users/{user-id}/photo'].delete
$.paths['/users/{user-id}/photo'].patch
$.paths['/users/{user-id}/photo/$value'].get
$.paths['/users/{user-id}/photo/$value'].put
$.paths['/users/{user-id}/photo/$value'].delete
$.paths['/users/{user-id}/photos'].get
$.paths['/users/{user-id}/photos/{profilePhoto-id}'].get
$.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].get
$.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].put
$.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].delete
OpenAPI Overlay
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
title: API Evangelist conversational phrasing for Users.profile Photo API
version: 1.0.0
extends: openapi/azure-ad-users-profilephoto-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: 11
- target: $.paths['/users/{user-id}/photo'].get
update:
x-apievangelist-phrasing:
intent: Get a user's main profile photo metadata
effect: read
questions:
- Does this user have a profile photo set, and what size is their main one?
- What is the height and width of someone's primary profile picture?
instructions:
- text: Get the main profile photo details for user {user_id}.
slots:
user_id: path.user-id
- text: Show only the {fields} of {user_id}'s primary profile photo.
slots:
user_id: path.user-id
fields: query.$select
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photo'].delete
update:
x-apievangelist-phrasing:
intent: Remove a user's profile photo record
effect: destructive
questions:
- Can I delete the profile photo object for a user altogether?
- What removes the photo navigation property from someone's account?
instructions:
- text: Delete the profile photo record for user {user_id}.
slots:
user_id: path.user-id
- text: Remove the photo property from user {user_id} with ETag {etag}.
slots:
user_id: path.user-id
etag: header.If-Match
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photo'].patch
update:
x-apievangelist-phrasing:
intent: Update a user's profile photo properties
effect: write
questions:
- Can I change the recorded height and width on a user's photo metadata?
- Which profile photo fields are editable apart from the image itself?
instructions:
- text: Set the photo metadata for user {user_id} to height {height} and width {width}.
slots:
user_id: path.user-id
height: requestBody.height
width: requestBody.width
- text: Update the profile photo properties on {user_id}.
slots:
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photo/$value'].get
update:
x-apievangelist-phrasing:
intent: Download a user's profile picture
effect: read
questions:
- How do I download the actual image bytes of a colleague's profile picture?
- Can I show a user's avatar in my app by fetching their photo binary?
instructions:
- text: Download the profile picture image for user {user_id}.
slots:
user_id: path.user-id
- text: Save {user_id}'s avatar to a file.
slots:
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photo/$value'].put
update:
x-apievangelist-phrasing:
intent: Upload a new profile picture for a user
effect: write
questions:
- How do I upload a new profile picture for someone in my organization?
- Can I replace a user's avatar with a JPEG from our HR system?
instructions:
- text: Upload this image as the profile picture for user {user_id}.
slots:
user_id: path.user-id
- text: Replace {user_id}'s avatar with the attached photo.
slots:
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photo/$value'].delete
update:
x-apievangelist-phrasing:
intent: Delete a user's profile picture image
effect: destructive
questions:
- How do I clear a user's profile picture so the default initials show again?
- Can I remove just the image content of someone's main photo?
instructions:
- text: Delete the profile picture image for user {user_id}.
slots:
user_id: path.user-id
- text: Clear the avatar image on {user_id}.
slots:
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photos'].get
update:
x-apievangelist-phrasing:
intent: List a user's profile photo sizes
effect: read
questions:
- Which sizes of a user's profile photo are available?
- Can I get all the different resolutions of someone's avatar in one call?
instructions:
- text: List the available profile photo sizes for user {user_id}.
slots:
user_id: path.user-id
- text: Show the photo size variants for {user_id} filtered by {filter}.
slots:
user_id: path.user-id
filter: query.$filter
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photos/{profilePhoto-id}'].get
update:
x-apievangelist-phrasing:
intent: Get details of one photo size for a user
effect: read
questions:
- What are the height and width of one specific photo size a user has?
- Can I read the metadata of a single sized user photo without downloading the image?
instructions:
- text: Get the metadata for photo size {photo_id} of user {user_id}.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
- text: Show only {fields} for sized photo {photo_id} in {user_id}'s photo collection.
slots:
fields: query.$select
photo_id: path.profilePhoto-id
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].get
update:
x-apievangelist-phrasing:
intent: Download a specific size of a user's photo
effect: read
questions:
- Can I download a small thumbnail version of a user's avatar instead of the full image?
- How do I fetch the image bytes of one specific photo size?
instructions:
- text: Download the {photo_id} size image of user {user_id}'s photo.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
- text: Save the {photo_id} thumbnail of {user_id}'s avatar.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].put
update:
x-apievangelist-phrasing:
intent: Upload the image for one photo size
effect: write
questions:
- Can I upload an image for just one specific size of a user's photo?
- How do I replace a single size variant of someone's avatar?
instructions:
- text: Upload this image as the {photo_id} size of user {user_id}'s photo.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
- text: Replace the {photo_id} variant image for {user_id}.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
method: generated
generated: '2026-10-01'
- target: $.paths['/users/{user-id}/photos/{profilePhoto-id}/$value'].delete
update:
x-apievangelist-phrasing:
intent: Delete the image for one photo size
effect: destructive
questions:
- Can I delete the image content of only one size variant of a user's photo?
- How do I remove a single thumbnail size from someone's avatar set?
instructions:
- text: Delete the {photo_id} size image from user {user_id}'s photos.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
- text: Clear the {photo_id} variant image for {user_id}.
slots:
photo_id: path.profilePhoto-id
user_id: path.user-id
method: generated
generated: '2026-10-01'