# 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 Facelists API
  version: 1.0.0
extends: openapi/microsoft-azure-facelists-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: 7
- target: $.paths['/facelists/{faceListId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a face list and its faces
      effect: read
      questions:
      - How can I see which faces are stored in a face list?
      - Does fetching a face list tell me its recognition model?
      instructions:
      - text: Get face list {faceListId} with its faces.
        slots:
          faceListId: path.faceListId
      - text: Show face list {faceListId} including recognition model {returnModel}.
        slots:
          faceListId: path.faceListId
          returnModel: query.returnRecognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists/{faceListId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create an empty face list
      effect: write
      questions:
      - How do I create a face list to use with Find Similar?
      - How many face lists can one subscription have?
      - Can I choose the recognition model when creating a face list?
      instructions:
      - text: Create face list {faceListId} named {name}.
        slots:
          faceListId: path.faceListId
          name: requestBody.name
      - text: Create face list {faceListId} named {name} using recognition model {recognitionModel}.
        slots:
          faceListId: path.faceListId
          name: requestBody.name
          recognitionModel: requestBody.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists/{faceListId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a face list
      effect: destructive
      questions:
      - Can I delete a whole face list and the face features stored in it?
      - What removes a face list I created?
      instructions:
      - text: Delete face list {faceListId}.
        slots:
          faceListId: path.faceListId
      - text: Remove face list {faceListId} and all its stored faces.
        slots:
          faceListId: path.faceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists/{faceListId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or update a face list
      effect: write
      questions:
      - How do I rename a face list or change its user data?
      - Can I edit a face list's userData after creating it?
      instructions:
      - text: Rename face list {faceListId} to {name}.
        slots:
          faceListId: path.faceListId
          name: requestBody.name
      - text: Set user data on face list {faceListId} to {userData}.
        slots:
          faceListId: path.faceListId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all face lists
      effect: read
      questions:
      - Which face lists exist in my Face resource?
      - Can listing face lists also show each one's recognition model?
      instructions:
      - text: List all my face lists.
      - text: List face lists and include recognition model {returnModel}.
        slots:
          returnModel: query.returnRecognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists/{faceListId}/persistedfaces/{persistedFaceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a face from a face list
      effect: destructive
      questions:
      - How do I remove one face from a face list?
      - Can I delete a single persisted face without deleting the list?
      instructions:
      - text: Delete face {persistedFaceId} from face list {faceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          faceListId: path.faceListId
      - text: Remove persisted face {persistedFaceId} out of list {faceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          faceListId: path.faceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/facelists/{faceListId}/persistedfaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a face from an image URL to a face list
      effect: write
      questions:
      - How do I add a face from an image URL to a face list?
      - What is the maximum number of faces a face list can hold?
      - If the image has several faces, can I pick which one gets added?
      instructions:
      - text: Add a face to face list {faceListId}.
        slots:
          faceListId: path.faceListId
      - text: Add the face at rectangle {targetFace} to face list {faceListId}.
        slots:
          targetFace: query.targetFace
          faceListId: path.faceListId
      - text: Add a face to list {faceListId} tagged with user data {userData}.
        slots:
          faceListId: path.faceListId
          userData: query.userData
      method: generated
      generated: '2026-09-26'