# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Purview Entity API
  version: 1.0.0
extends: openapi/microsoft-purview-entity-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: 19
- target: $.paths['/api/atlas/v2/entity'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a single catalog entity
      effect: write
      questions:
      - How do I register one data asset in the Purview catalog?
      - Will Purview update an asset that already exists with the same qualifiedName?
      instructions:
      - text: Create or update the catalog entity {entity}.
        slots:
          entity: requestBody.entity
      - text: Upsert entity {entity} together with referred entities {refs}.
        slots:
          entity: requestBody.entity
          refs: requestBody.referredEntities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity's full definition
      effect: read
      questions:
      - How can I read everything Purview knows about one asset by its GUID?
      - Can I fetch an entity without its relationships to keep the response small?
      instructions:
      - text: Get the full definition of entity {guid}.
        slots:
          guid: path.guid
      - text: 'Fetch entity {guid} ignoring relationships: {ignore}.'
        slots:
          guid: path.guid
          ignore: query.ignoreRelationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one entity by GUID
      effect: destructive
      questions:
      - Can I remove a single asset from the catalog using its GUID?
      - What is the way to delete one entity that was registered by mistake?
      instructions:
      - text: Delete the single entity {guid}.
        slots:
          guid: path.guid
      - text: Remove asset {guid} from the catalog.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch several entities by their GUIDs
      effect: read
      questions:
      - Can I retrieve many assets in one call when I have a list of GUIDs?
      - Which call returns multiple entities at once with minimal extra info?
      instructions:
      - text: Get the entities with GUIDs {guids}.
        slots:
          guids: query.guid
      - text: Fetch entities {guids} in bulk with minimal extended info {min}.
        slots:
          guids: query.guid
          min: query.minExtInfo
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update many entities at once
      effect: write
      questions:
      - How do I load a batch of assets into the catalog in one request?
      - Can I upsert many entities together with the entities they reference?
      instructions:
      - text: Bulk create or update entities {entities}.
        slots:
          entities: requestBody.entities
      - text: Upsert the batch {entities} with referred entities {refs}.
        slots:
          entities: requestBody.entities
          refs: requestBody.referredEntities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/bulk'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete many entities at once
      effect: destructive
      questions:
      - Can I delete a whole list of assets in one call?
      - Is there a bulk delete for entities by GUID?
      instructions:
      - text: Bulk delete the entities with GUIDs {guids}.
        slots:
          guids: query.guid
      - text: 'Remove all of these assets from the catalog in one go: {guids}.'
        slots:
          guids: query.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/classification/{classificationName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one classification on an entity
      effect: read
      questions:
      - Does a given asset carry a specific classification?
      - What are the details of one classification applied to an entity?
      instructions:
      - text: Get classification {classification} on entity {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      - text: Check whether asset {guid} has the {classification} classification.
        slots:
          guid: path.guid
          classification: path.classificationName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/classification/{classificationName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a classification from an entity
      effect: destructive
      questions:
      - How do I take a wrong classification off an asset?
      - Can I delete just one classification from an entity?
      instructions:
      - text: Remove classification {classification} from entity {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      - text: Unclassify asset {guid} as {classification}.
        slots:
          guid: path.guid
          classification: path.classificationName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/classifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List all classifications on an entity
      effect: read
      questions:
      - What classifications have been applied to a given asset?
      - Which sensitive data types were detected on an entity?
      instructions:
      - text: List the classifications on entity {guid}.
        slots:
          guid: path.guid
      - text: Show every classification tagged on asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/classifications'].put
  update:
    x-apievangelist-phrasing:
      intent: Update existing classifications on an entity
      effect: write
      questions:
      - How do I change the attributes of classifications already on an asset?
      - Can I modify classifications an entity already has?
      instructions:
      - text: Update the existing classifications on entity {guid}.
        slots:
          guid: path.guid
      - text: Modify classifications already applied to asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/classifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Add classifications to an entity
      effect: write
      questions:
      - How do I tag an asset with additional classifications?
      - Can I add new classifications to one entity by GUID?
      instructions:
      - text: Add classifications to entity {guid}.
        slots:
          guid: path.guid
      - text: Tag asset {guid} with new classifications.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/labels'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace the labels on an entity
      effect: write
      questions:
      - How do I overwrite all labels on an asset with a new set?
      - Can I set an entity's labels to exactly a given list?
      instructions:
      - text: Set the labels on entity {guid}, replacing any existing ones.
        slots:
          guid: path.guid
      - text: Overwrite asset {guid}'s labels.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/labels'].post
  update:
    x-apievangelist-phrasing:
      intent: Add labels to an entity
      effect: write
      questions:
      - Can I append labels to an asset without touching its current ones?
      - How do I add a label to a single entity?
      instructions:
      - text: Add labels to entity {guid}.
        slots:
          guid: path.guid
      - text: Append new labels to asset {guid} keeping the existing ones.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/labels'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove labels from an entity
      effect: destructive
      questions:
      - How do I delete specific labels from an asset?
      - Can I strip labels off one entity?
      instructions:
      - text: Remove labels from entity {guid}.
        slots:
          guid: path.guid
      - text: Strip the given labels off asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/bulk/setClassifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Set classifications on many entities
      effect: write
      questions:
      - Can I classify a batch of assets in one request?
      - How do I apply classifications across multiple entities at once?
      instructions:
      - text: Set classifications in bulk using the entity header map {map}.
        slots:
          map: requestBody.guidHeaderMap
      - text: Apply classifications to many assets via {map}.
        slots:
          map: requestBody.guidHeaderMap
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/businessmetadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update business metadata on an entity
      effect: write
      questions:
      - How do I attach business metadata attributes to an asset?
      - Can I overwrite an entity's business metadata instead of merging it?
      instructions:
      - text: Add business metadata to entity {guid}.
        slots:
          guid: path.guid
      - text: Set business metadata on asset {guid} with overwrite set to {overwrite}.
        slots:
          guid: path.guid
          overwrite: query.isOverwrite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/businessmetadata'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove business metadata from an entity
      effect: destructive
      questions:
      - How do I clear business metadata from an asset?
      - Can I delete the business attributes attached to one entity?
      instructions:
      - text: Remove business metadata from entity {guid}.
        slots:
          guid: path.guid
      - text: Clear the business attributes on asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/bulk/collection/{collectionId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Move entities into a collection
      effect: write
      questions:
      - How do I move assets from one Purview collection to another?
      - Can I relocate several entities to a target collection at once?
      instructions:
      - text: Move entities {guids} to collection {collection}.
        slots:
          guids: requestBody.entityGuids
          collection: path.collectionId
      - text: 'Relocate these assets into collection {collection}: {guids}.'
        slots:
          collection: path.collectionId
          guids: requestBody.entityGuids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/entity/guid/{guid}/header'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity's header summary
      effect: read
      questions:
      - Is there a lightweight way to get just an asset's name, type and status?
      - What does the header of an entity contain?
      instructions:
      - text: Get the header for entity {guid}.
        slots:
          guid: path.guid
      - text: Show only the summary header of asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'