# 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 Largefacelists API
  version: 1.0.0
extends: openapi/microsoft-azure-largefacelists-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: 12
- target: $.paths['/largefacelists/{largeFaceListId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a large face list
      effect: read
      questions:
      - How do I see the name and user data of a large face list?
      - Which recognition model was a given large face list created with?
      instructions:
      - text: Get large face list {largeFaceListId}.
        slots:
          largeFaceListId: path.largeFaceListId
      - text: Show large face list {largeFaceListId} with returnRecognitionModel set to {returnRecognitionModel}.
        slots:
          largeFaceListId: path.largeFaceListId
          returnRecognitionModel: query.returnRecognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create an empty large face list
      effect: write
      questions:
      - How do I create a large face list to use with Find Similar in Azure Face?
      - How many faces can a large face list hold?
      - Can I pick the recognition model when creating a face list?
      instructions:
      - text: Create large face list {largeFaceListId} named {name}.
        slots:
          largeFaceListId: path.largeFaceListId
          name: requestBody.name
      - text: Set up a new large face list {largeFaceListId} called {name} using recognition model {recognitionModel}.
        slots:
          largeFaceListId: path.largeFaceListId
          name: requestBody.name
          recognitionModel: requestBody.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a large face list
      effect: destructive
      questions:
      - How do I remove an entire large face list and its faces?
      - Can I delete a face list I no longer use for matching?
      instructions:
      - text: Delete large face list {largeFaceListId}.
        slots:
          largeFaceListId: path.largeFaceListId
      - text: Remove the whole face list {largeFaceListId} permanently.
        slots:
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or update a large face list
      effect: write
      questions:
      - Can I rename a large face list after creating it?
      - How do I change the user data attached to a face list?
      instructions:
      - text: Rename large face list {largeFaceListId} to {name}.
        slots:
          largeFaceListId: path.largeFaceListId
          name: requestBody.name
      - text: Set the userData of face list {largeFaceListId} to {userData}.
        slots:
          largeFaceListId: path.largeFaceListId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/training'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a large face list's training status
      effect: read
      questions:
      - Has training finished on my large face list yet?
      - How can I tell whether face list training is still running or failed?
      instructions:
      - text: Check the training status of large face list {largeFaceListId}.
        slots:
          largeFaceListId: path.largeFaceListId
      - text: Tell me if training for face list {largeFaceListId} has completed.
        slots:
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists'].get
  update:
    x-apievangelist-phrasing:
      intent: List large face lists
      effect: read
      questions:
      - What large face lists exist in my Face resource?
      - Can I page through face lists starting after a particular id?
      instructions:
      - text: List all my large face lists.
      - text: List up to {top} large face lists starting after {start}.
        slots:
          top: query.top
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/train'].post
  update:
    x-apievangelist-phrasing:
      intent: Start training a large face list
      effect: write
      questions:
      - Do I need to train a large face list before calling Find Similar?
      - How do I kick off training after adding new faces to a list?
      instructions:
      - text: Train large face list {largeFaceListId}.
        slots:
          largeFaceListId: path.largeFaceListId
      - text: Queue a training job for face list {largeFaceListId} now that I've added faces.
        slots:
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a persisted face in a large face list
      effect: read
      questions:
      - How do I look up the user data stored on one face in a face list?
      - Can I retrieve a single persisted face by its id?
      instructions:
      - text: Get persisted face {persistedFaceId} from large face list {largeFaceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
      - text: Show the userData saved on face {persistedFaceId} in list {largeFaceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a face from a large face list
      effect: destructive
      questions:
      - How do I delete one person's face from a large face list?
      - Are face deletions on the same list processed one at a time?
      instructions:
      - text: Delete face {persistedFaceId} from large face list {largeFaceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
      - text: Remove persisted face {persistedFaceId} out of list {largeFaceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update user data on a persisted face
      effect: write
      questions:
      - Can I change the label stored on a face I already added to a list?
      - Which field of a persisted face can be edited after it's added?
      instructions:
      - text: Set userData of face {persistedFaceId} in list {largeFaceListId} to {userData}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
          userData: requestBody.userData
      - text: Relabel persisted face {persistedFaceId} in large face list {largeFaceListId}.
        slots:
          persistedFaceId: path.persistedFaceId
          largeFaceListId: path.largeFaceListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/persistedfaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List faces in a large face list
      effect: read
      questions:
      - How do I see every face stored in one large face list?
      - Can I page through the persisted faces of a list in batches?
      instructions:
      - text: List the faces in large face list {largeFaceListId}.
        slots:
          largeFaceListId: path.largeFaceListId
      - text: Return {top} persisted faces from list {largeFaceListId} after face {start}.
        slots:
          top: query.top
          largeFaceListId: path.largeFaceListId
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largefacelists/{largeFaceListId}/persistedfaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a face image to a large face list
      effect: write
      questions:
      - How do I add a new face photo to a large face list?
      - What if my image contains several faces and I only want to add one?
      - Can I choose the detection model when adding a face to a list?
      instructions:
      - text: Add a face to large face list {largeFaceListId} with userData {userData}.
        slots:
          largeFaceListId: path.largeFaceListId
          userData: query.userData
      - text: Add only the face inside rectangle {targetFace} of the image to list {largeFaceListId}.
        slots:
          targetFace: query.targetFace
          largeFaceListId: path.largeFaceListId
      - text: Add a face to list {largeFaceListId} using detection model {detectionModel}.
        slots:
          largeFaceListId: path.largeFaceListId
          detectionModel: query.detectionModel
      method: generated
      generated: '2026-09-26'