# 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 Persongroups API
  version: 1.0.0
extends: openapi/microsoft-azure-person-groups-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: 16
- target: $.paths['/persongroups/{personGroupId}/persons'].get
  update:
    x-apievangelist-phrasing:
      intent: List the people in a person group
      effect: read
      questions:
      - Who is enrolled in a given Face person group?
      - Can I page through persons in a person group starting after a certain personId?
      instructions:
      - text: List all persons in person group {group}.
        slots:
          group: path.personGroupId
      - text: Show {top} persons in group {group} starting after {start}.
        slots:
          top: query.top
          group: path.personGroupId
          start: query.start
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new person to a person group
      effect: write
      questions:
      - How do I enroll a new person in a Face person group?
      - Can I attach custom userData when creating a person?
      instructions:
      - text: Create a person named {name} in person group {group}.
        slots:
          name: requestBody.name
          group: path.personGroupId
      - text: Add person {name} to group {group} with user data {user_data}.
        slots:
          name: requestBody.name
          group: path.personGroupId
          user_data: requestBody.userData
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a person and their registered faces
      effect: read
      questions:
      - Which faces are registered to a specific person in my person group?
      - What name and userData are stored for one person?
      instructions:
      - text: Get person {person} from person group {group}.
        slots:
          person: path.personId
          group: path.personGroupId
      - text: Show the persisted face ids registered for person {person} in group {group}.
        slots:
          person: path.personId
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a person from a person group
      effect: destructive
      questions:
      - If I delete a person from a person group, are their faces and features removed too?
      - How can I remove someone from a Face person group?
      instructions:
      - text: Delete person {person} from person group {group}.
        slots:
          person: path.personId
          group: path.personGroupId
      - text: Remove person {person} and all their face data from group {group}.
        slots:
          person: path.personId
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a person or change their userData
      effect: write
      questions:
      - Can I rename a person already enrolled in a person group?
      - What can I change on an existing person besides their faces?
      instructions:
      - text: Rename person {person} in group {group} to {name}.
        slots:
          person: path.personId
          group: path.personGroupId
          name: requestBody.name
      - text: Set user data {user_data} on person {person} in group {group}.
        slots:
          user_data: requestBody.userData
          person: path.personId
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one persisted face of a person
      effect: read
      questions:
      - What information is stored for a single persisted face of a person?
      - Can I read the userData attached to one of a person's faces?
      instructions:
      - text: Get persisted face {face} of person {person} in group {group}.
        slots:
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
      - text: Show the stored details of face {face} for person {person}, group {group}.
        slots:
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a face from a person
      effect: destructive
      questions:
      - How do I remove one bad face image from a person without deleting the person?
      - Are face deletions for the same person processed one at a time?
      instructions:
      - text: Delete face {face} from person {person} in group {group}.
        slots:
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
      - text: Remove persisted face {face} from person {person} (group {group}).
        slots:
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the userData of a person's face
      effect: write
      questions:
      - Can I change the userData on a face that is already registered to a person?
      - Which field of an existing persisted face can I edit?
      instructions:
      - text: Set user data {user_data} on face {face} of person {person} in group {group}.
        slots:
          user_data: requestBody.userData
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
      - text: Update the note on persisted face {face} for person {person}, group {group}, to {user_data}.
        slots:
          face: path.persistedFaceId
          person: path.personId
          group: path.personGroupId
          user_data: requestBody.userData
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a person group's name and settings
      effect: read
      questions:
      - Which recognition model does my person group use?
      - What name and userData are set on a person group?
      instructions:
      - text: Get person group {group}.
        slots:
          group: path.personGroupId
      - text: Show person group {group} including its recognition model ({return_model}).
        slots:
          group: path.personGroupId
          return_model: query.returnRecognitionModel
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a person group
      effect: write
      questions:
      - How do I set up a new person group for face identification?
      - Can I choose the recognition model when creating a person group?
      instructions:
      - text: Create person group {group} named {name}.
        slots:
          group: path.personGroupId
          name: requestBody.name
      - text: Create person group {group} called {name} using recognition model {model}.
        slots:
          group: path.personGroupId
          name: requestBody.name
          model: requestBody.recognitionModel
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a person group and all its people
      effect: destructive
      questions:
      - Does deleting a person group also delete every person's face features?
      - Can I delete an entire Face person group at once?
      instructions:
      - text: Delete person group {group}.
        slots:
          group: path.personGroupId
      - text: Remove person group {group} along with everyone enrolled in it.
        slots:
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a person group or change its userData
      effect: write
      questions:
      - Can I rename an existing person group?
      - If I only send userData when updating a person group, is the name kept?
      instructions:
      - text: Rename person group {group} to {name}.
        slots:
          group: path.personGroupId
          name: requestBody.name
      - text: Change the group-level user data of person group {group} to {user_data}.
        slots:
          user_data: requestBody.userData
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/training'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a person group's training status
      effect: read
      questions:
      - Has training finished on my person group yet?
      - Is my person group training still running?
      instructions:
      - text: Check the training status of person group {group}.
        slots:
          group: path.personGroupId
      - text: Tell me whether training on group {group} is completed or ongoing.
        slots:
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List person groups
      effect: read
      questions:
      - What person groups exist on my Face resource?
      - Can I page through person groups in alphabetical order of their id?
      instructions:
      - text: List all my person groups.
      - text: List {top} person groups after id {start}.
        slots:
          top: query.top
          start: query.start
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/train'].post
  update:
    x-apievangelist-phrasing:
      intent: Train a person group
      effect: write
      questions:
      - How do I retrain a person group after adding new faces?
      - Does queueing person group training start it right away?
      instructions:
      - text: Train person group {group}.
        slots:
          group: path.personGroupId
      - text: Queue a training run for group {group} now that faces were added.
        slots:
          group: path.personGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/persongroups/{personGroupId}/persons/{personId}/persistedfaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a face image to a person
      effect: write
      questions:
      - How do I add a new face photo to a person for identification?
      - Can I pick one face from a group photo using a target rectangle?
      instructions:
      - text: Add a face to person {person} in group {group}.
        slots:
          person: path.personId
          group: path.personGroupId
      - text: Add the face at rectangle {target} to person {person} in group {group} using detection model {model}.
        slots:
          target: query.targetFace
          person: path.personId
          group: path.personGroupId
          model: query.detectionModel
      method: generated
      generated: '2026-10-01'