# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Face Client Person Directory API
  version: 1.0.0
extends: openapi/microsoft-azure-persondirectory-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/persons'].get
  update:
    x-apievangelist-phrasing:
      intent: List people in the person directory
      effect: read
      questions:
      - Who is registered in my Face person directory?
      - Can I page through the person directory a set number of people at a time?
      instructions:
      - text: List the people in my person directory.
      - text: Show the next {top} people in the person directory starting after {start}.
        slots:
          top: query.top
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a person to the person directory
      effect: write
      questions:
      - How do I register a new person in the Face person directory?
      - Can I attach my own user data to a person when I create them?
      instructions:
      - text: Create a person named {name} in the person directory.
        slots:
          name: requestBody.name
      - text: Add new person {name} to the directory with user data {userData}.
        slots:
          name: requestBody.name
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a person's details from the directory
      effect: read
      questions:
      - What name, user data and persisted face ids are stored for one person?
      - Can I look up a single person in the directory by their id?
      instructions:
      - text: Show person {personId} from the person directory.
        slots:
          personId: path.personId
      - text: Get the name and user data recorded for person {personId}.
        slots:
          personId: path.personId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a person from the directory
      effect: destructive
      questions:
      - How do I remove someone and all their face data from the person directory?
      - Does deleting a person also remove their persisted faces?
      instructions:
      - text: Delete person {personId} from the person directory.
        slots:
          personId: path.personId
      - text: Remove {personId} and all of their stored face features.
        slots:
          personId: path.personId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a person or change their user data
      effect: write
      questions:
      - How can I change the name of a person already in the directory?
      - Can I edit the user data stored on an existing person?
      instructions:
      - text: Rename person {personId} to {name}.
        slots:
          personId: path.personId
          name: requestBody.name
      - text: Set the user data on person {personId} to {userData}.
        slots:
          personId: path.personId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List a person's faces for a recognition model
      effect: read
      questions:
      - Which faces are enrolled for a person under a given recognition model?
      - How many persisted faces does someone have in the directory?
      instructions:
      - text: List the faces of person {personId} for recognition model {recognitionModel}.
        slots:
          personId: path.personId
          recognitionModel: path.recognitionModel
      - text: Show all persisted face ids enrolled for {personId} under {recognitionModel}.
        slots:
          personId: path.personId
          recognitionModel: path.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a face to a person
      effect: write
      questions:
      - How do I enroll a new face photo for someone in the person directory?
      - Can I pick which face to use when the image contains more than one?
      instructions:
      - text: Add a new face to person {personId} for recognition model {recognitionModel}.
        slots:
          personId: path.personId
          recognitionModel: path.recognitionModel
      - text: Enroll the face at rectangle {targetFace} for person {personId} under {recognitionModel} using detection model {detectionModel}.
        slots:
          targetFace: query.targetFace
          personId: path.personId
          recognitionModel: path.recognitionModel
          detectionModel: query.detectionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces/{persistedFaceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of a person's enrolled faces
      effect: read
      questions:
      - What information is stored for one specific enrolled face of a person?
      - Can I read the user data attached to a single persisted face?
      instructions:
      - text: Show face {persistedFaceId} of person {personId} for recognition model {recognitionModel}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
      - text: Get the stored data for persisted face {persistedFaceId} on {personId} under {recognitionModel}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces/{persistedFaceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of a person's faces
      effect: destructive
      questions:
      - How do I remove a bad face photo from someone's enrollment without deleting the person?
      - Can I delete just one persisted face from a person?
      instructions:
      - text: Delete face {persistedFaceId} from person {personId} for recognition model {recognitionModel}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
      - text: Remove persisted face {persistedFaceId} from {personId} under {recognitionModel}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces/{persistedFaceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the user data on a person's face
      effect: write
      questions:
      - How do I change the user data attached to one enrolled face?
      - Can I edit a persisted face's details after enrolling it?
      instructions:
      - text: Set the user data on face {persistedFaceId} of person {personId} under {recognitionModel} to {userData}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
          userData: requestBody.userData
      - text: Update persisted face {persistedFaceId} for {personId} with recognition model {recognitionModel}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          recognitionModel: path.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups/{dynamicPersonGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dynamic person group
      effect: read
      questions:
      - What name and user data does a dynamic person group have?
      - Can I look up one dynamic person group by its id?
      instructions:
      - text: Show dynamic person group {dynamicPersonGroupId}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
      - text: Get the metadata for dynamic person group {dynamicPersonGroupId}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups/{dynamicPersonGroupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a dynamic person group
      effect: write
      questions:
      - How do I create a group of directory people to match faces against?
      - Can I add people to a dynamic person group at the moment I create it?
      instructions:
      - text: Create dynamic person group {dynamicPersonGroupId} named {name}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
          name: requestBody.name
      - text: Create group {dynamicPersonGroupId} containing persons {addPersonIds}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
          addPersonIds: requestBody.addPersonIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups/{dynamicPersonGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dynamic person group
      effect: destructive
      questions:
      - How do I delete a dynamic person group I no longer need?
      - Are the people in a dynamic person group deleted along with the group?
      instructions:
      - text: Delete dynamic person group {dynamicPersonGroupId}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
      - text: Remove group {dynamicPersonGroupId} but keep its people in the directory.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups/{dynamicPersonGroupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a dynamic person group's members or name
      effect: write
      questions:
      - How do I add or remove people from an existing dynamic person group?
      - Can I rename a dynamic person group?
      instructions:
      - text: Add persons {addPersonIds} to dynamic person group {dynamicPersonGroupId}.
        slots:
          addPersonIds: requestBody.addPersonIds
          dynamicPersonGroupId: path.dynamicPersonGroupId
      - text: Remove persons {removePersonIds} from group {dynamicPersonGroupId}.
        slots:
          removePersonIds: requestBody.removePersonIds
          dynamicPersonGroupId: path.dynamicPersonGroupId
      - text: Rename dynamic person group {dynamicPersonGroupId} to {name}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups/{dynamicPersonGroupId}/persons'].get
  update:
    x-apievangelist-phrasing:
      intent: List the people in a dynamic person group
      effect: read
      questions:
      - Who belongs to a particular dynamic person group?
      - Can I page through the members of a dynamic person group?
      instructions:
      - text: List the people in dynamic person group {dynamicPersonGroupId}.
        slots:
          dynamicPersonGroupId: path.dynamicPersonGroupId
      - text: Show the first {top} members of group {dynamicPersonGroupId}.
        slots:
          top: query.top
          dynamicPersonGroupId: path.dynamicPersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamicpersongroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List dynamic person groups
      effect: read
      questions:
      - Which dynamic person groups exist in my person directory?
      - How many dynamic person groups have been set up?
      instructions:
      - text: List all dynamic person groups in the person directory.
      - text: Show {top} dynamic person groups starting after {start}.
        slots:
          top: query.top
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/persons/{personId}/dynamicPersonGroupReferences'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups a person belongs to
      effect: read
      questions:
      - Which dynamic person groups is a given person a member of?
      - Before deleting someone, how do I see which groups reference them?
      instructions:
      - text: List the dynamic person groups that include person {personId}.
        slots:
          personId: path.personId
      - text: Show which groups reference {personId}.
        slots:
          personId: path.personId
      method: generated
      generated: '2026-09-26'