# 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 Entity API
  version: 1.0.0
extends: openapi/microsoft-azure-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: 37
- target: $.paths['/entity/moveTo'].post
  update:
    x-apievangelist-phrasing:
      intent: Move data assets into another collection
      effect: write
      questions:
      - Can I move several catalog assets into a different Purview collection at once?
      - What do I need to relocate entities from one collection to another?
      instructions:
      - text: Move entities {entity_guids} into collection {collection_id}.
        slots:
          entity_guids: requestBody.entityGuids
          collection_id: query.collectionId
      - text: Reassign these assets to collection {collection_id}.
        slots:
          collection_id: query.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a single data map entity
      effect: write
      questions:
      - How do I register one asset, like a hive table, in the Purview Data Map?
      - Will posting an entity with an existing qualifiedName update it instead of creating a duplicate?
      - Can I control how business attributes are merged when I upsert a single entity?
      instructions:
      - text: 'Create or update this single entity in the data map: {entity}.'
        slots:
          entity: requestBody.entity
      - text: Upsert entity {entity} using business attribute update behavior {behavior}.
        slots:
          entity: requestBody.entity
          behavior: query.businessAttributeUpdateBehavior
      method: generated
      generated: '2026-10-01'
- target: $.paths['/atlas/v2/entity/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch several entities by their GUIDs
      effect: read
      questions:
      - How can I look up many catalog entities at once when I have their GUIDs?
      - Can I skip relationship details when pulling a batch of entities by GUID?
      instructions:
      - text: Get the entities with GUIDs {guids}.
        slots:
          guids: query.guid
      - text: Fetch entities {guids} without their relationships.
        slots:
          guids: query.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update many entities in one call
      effect: write
      questions:
      - How do I load a whole batch of assets into the Purview Data Map in one request?
      - Can a bulk entity upsert include the referred entities they point to?
      instructions:
      - text: 'Bulk create or update these entities in the data map: {entities}.'
        slots:
          entities: requestBody.entities
      - text: Upsert the entity list {entities} in bulk along with referred entities {referred}.
        slots:
          entities: requestBody.entities
          referred: requestBody.referredEntities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/atlas/v2/entity/bulk'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several entities by GUID
      effect: destructive
      questions:
      - Can I remove a whole list of catalog entities at once by GUID?
      - What happens when I bulk delete entities from the data map?
      instructions:
      - text: Delete the entities with GUIDs {guids}.
        slots:
          guids: query.guid
      - text: Bulk remove catalog assets {guids}.
        slots:
          guids: query.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/bulk/classification'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply one classification to many entities
      effect: write
      questions:
      - How do I tag lots of assets with the same classification in one go?
      - Can one classification be attached to multiple entities in bulk?
      instructions:
      - text: Apply classification {classification} to entities {entity_guids}.
        slots:
          classification: requestBody.classification
          entity_guids: requestBody.entityGuids
      - text: Mark all of {entity_guids} with the same classification.
        slots:
          entity_guids: requestBody.entityGuids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity's full definition by GUID
      effect: read
      questions:
      - How do I see everything the catalog knows about one asset by its GUID?
      - Can I get an entity's full definition with minimal extra info?
      instructions:
      - text: Show the full definition of entity {guid}.
        slots:
          guid: path.guid
      - text: Get entity {guid} and ignore its relationships.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one attribute on an entity by GUID
      effect: write
      questions:
      - Can I change just a single attribute of an entity without resending the whole thing?
      - Which attribute types can be updated one at a time on an entity?
      instructions:
      - text: Set attribute {attribute} on entity {guid}.
        slots:
          attribute: query.name
          guid: path.guid
      - text: Update only the {attribute} attribute of asset {guid}.
        slots:
          attribute: query.name
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one entity by GUID
      effect: destructive
      questions:
      - How do I remove a single data asset from the catalog using its GUID?
      - Is deleting one entity by GUID permanent?
      instructions:
      - text: Delete entity {guid}.
        slots:
          guid: path.guid
      - text: Remove the catalog asset with GUID {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/classification/{classificationName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one named classification on an entity
      effect: read
      questions:
      - How do I check whether an entity carries a specific classification?
      - What are the details of a particular classification on an asset?
      instructions:
      - text: Get classification {classification} on entity {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      - text: Show the {classification} classification attached to asset {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/classification/{classificationName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a classification from an entity by GUID
      effect: destructive
      questions:
      - Can I take a single classification off an asset I know by GUID?
      - How do I drop a wrong classification from an entity?
      instructions:
      - text: Remove classification {classification} from entity {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      - text: Delete the {classification} tag from asset {guid}.
        slots:
          classification: path.classificationName
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/classifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List all classifications on an entity
      effect: read
      questions:
      - Which classifications are applied to this asset?
      - How do I list every classification on an entity by GUID?
      instructions:
      - text: List all classifications on entity {guid}.
        slots:
          guid: path.guid
      - text: Show every classification attached to asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/classifications'].put
  update:
    x-apievangelist-phrasing:
      intent: Update existing classifications on an entity
      effect: write
      questions:
      - Can I change the attributes of classifications already on an entity?
      - How do I edit classifications that are already applied to an asset by GUID?
      instructions:
      - text: Update the existing classifications on entity {guid}.
        slots:
          guid: path.guid
      - text: Modify classification values already applied to asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/classifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Add classifications to an entity by GUID
      effect: write
      questions:
      - How do I attach new classifications to a single asset?
      - Can I add more than one classification to an entity at a time?
      instructions:
      - text: Add classifications to entity {guid}.
        slots:
          guid: path.guid
      - text: Attach new classification tags to asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity by type and qualified name
      effect: read
      questions:
      - How do I find an entity when I know its type and qualifiedName but not its GUID?
      - Can I look up a single asset by unique attribute instead of GUID?
      instructions:
      - text: Get the {type_name} entity with qualified name {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Look up the {type_name} asset named {qualified_name} without relationships.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update part of an entity by qualified name
      effect: write
      questions:
      - Can I update some attributes of an entity identified by type and qualifiedName?
      - Is a null value allowed when partially updating an entity by unique attribute?
      instructions:
      - text: Update {type_name} entity {qualified_name} with {entity}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
          entity: requestBody.entity
      - text: Patch attributes on the {type_name} asset whose qualified name is {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an entity by type and qualified name
      effect: destructive
      questions:
      - How do I delete an asset when I only know its type and qualifiedName?
      - Can I remove an entity without looking up its GUID first?
      instructions:
      - text: Delete the {type_name} entity with qualified name {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Remove {type_name} asset {qualified_name} from the catalog.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/classification/{classificationName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a classification by qualified name
      effect: destructive
      questions:
      - Can I drop a classification from an entity identified by qualifiedName?
      - How do I untag an asset found by type and unique attribute?
      instructions:
      - text: Using qualified name {qualified_name}, strip classification {classification} from that {type_name}.
        slots:
          classification: path.classificationName
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Take the {classification} tag off the {type_name} asset named {qualified_name}.
        slots:
          classification: path.classificationName
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/classifications'].put
  update:
    x-apievangelist-phrasing:
      intent: Update classifications by qualified name
      effect: write
      questions:
      - How do I edit classifications on an entity I know by type and qualifiedName?
      - Can existing classifications be modified without the entity GUID?
      instructions:
      - text: Update classifications on {type_name} entity {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Revise the classification values on the {type_name} asset {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/classifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Add classifications by qualified name
      effect: write
      questions:
      - Can I classify an asset using its type and qualifiedName instead of GUID?
      - What's needed to attach a classification to an entity by unique attribute?
      instructions:
      - text: Look up {type_name} by qualified name {qualified_name} and attach classifications to it.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Classify the {type_name} asset named {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/bulk/setClassifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Set classifications across entities in bulk
      effect: write
      questions:
      - How do I set classifications on many entities with one request?
      - Can I replace classifications for a set of entity headers in bulk?
      instructions:
      - text: Set classifications in bulk using {guid_header_map}.
        slots:
          guid_header_map: requestBody.guidHeaderMap
      - text: 'Apply these per-entity classification sets in one call: {guid_header_map}.'
        slots:
          guid_header_map: requestBody.guidHeaderMap
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/bulk/uniqueAttribute/type/{typeName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch several entities by qualified names
      effect: read
      questions:
      - Can I retrieve many entities of one type by their qualifiedNames at once?
      - How do I bulk look up assets by unique attribute?
      instructions:
      - text: Get all {type_name} entities matching qualified names {qualified_names}.
        slots:
          type_name: path.typeName
          qualified_names: query.attr_N:qualifiedName
      - text: Bulk fetch {type_name} assets by unique attribute.
        slots:
          type_name: path.typeName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/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 the header of an entity?
      - What does an entity header include compared with the full definition?
      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-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/businessmetadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Add business metadata to an entity
      effect: write
      questions:
      - How do I attach business metadata to a catalog asset?
      - Can I overwrite all existing business metadata on an entity?
      instructions:
      - text: Add business metadata to entity {guid}.
        slots:
          guid: path.guid
      - text: Replace the business metadata on asset {guid} with overwrite set to {is_overwrite}.
        slots:
          guid: path.guid
          is_overwrite: query.isOverwrite
      method: generated
      generated: '2026-09-26'
- target: $.paths['/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 off an asset?
      - Can business metadata be removed from a single entity?
      instructions:
      - text: Remove business metadata from entity {guid}.
        slots:
          guid: path.guid
      - text: Strip the business metadata off asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/businessmetadata/{bmName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set attributes of a named business metadata
      effect: write
      questions:
      - Can I update the attributes of one business metadata type on an entity?
      - How do I fill in a specific business metadata set on an asset?
      instructions:
      - text: Update business metadata {bm_name} attributes on entity {guid}.
        slots:
          bm_name: path.bmName
          guid: path.guid
      - text: Add {bm_name} business metadata values to asset {guid}.
        slots:
          bm_name: path.bmName
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/businessmetadata/{bmName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete attributes of a named business metadata
      effect: destructive
      questions:
      - How do I remove the attributes of one business metadata type from an entity?
      - Can I delete just a single business metadata set from an asset?
      instructions:
      - text: Delete {bm_name} business metadata attributes from entity {guid}.
        slots:
          bm_name: path.bmName
          guid: path.guid
      - text: Clear the {bm_name} values on asset {guid}.
        slots:
          bm_name: path.bmName
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/businessmetadata/import/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the business metadata import template
      effect: read
      questions:
      - Where do I get a sample file for bulk-importing business metadata?
      - What format does the business metadata upload template use?
      instructions:
      - text: Download the sample business metadata import template.
      - text: Get the template for bulk business metadata uploads.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/businessmetadata/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import business metadata definitions from a file
      effect: write
      questions:
      - How do I bulk create business metadata by uploading a file?
      - Can I import business metadata attributes into the data map from a template file?
      instructions:
      - text: Upload {file} to create business metadata in bulk.
        slots:
          file: requestBody.uploadedInputStream
      - text: Import the business metadata file {file} into the data map.
        slots:
          file: requestBody.uploadedInputStream
      method: generated
      generated: '2026-10-01'
- target: $.paths['/atlas/v2/entity/guid/{guid}/labels'].put
  update:
    x-apievangelist-phrasing:
      intent: Add labels to an entity by GUID
      effect: write
      questions:
      - How do I add labels to an asset without removing the ones it has?
      - Can I append labels to an entity identified by GUID?
      instructions:
      - text: Add labels to entity {guid}.
        slots:
          guid: path.guid
      - text: Append new labels to asset {guid}, keeping existing ones.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/labels'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace the labels on an entity by GUID
      effect: write
      questions:
      - Can I overwrite all labels on an entity with a new set?
      - What happens to old labels when I set labels on an asset by GUID?
      instructions:
      - text: Set the labels on entity {guid}, replacing the current ones.
        slots:
          guid: path.guid
      - text: Overwrite asset {guid}'s labels with a new list.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/guid/{guid}/labels'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete labels from an entity by GUID
      effect: destructive
      questions:
      - How do I remove certain labels from an asset I know by GUID?
      - Can I delete specific labels from an entity?
      instructions:
      - text: Delete the given labels from entity {guid}.
        slots:
          guid: path.guid
      - text: Remove labels from asset {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/labels'].put
  update:
    x-apievangelist-phrasing:
      intent: Add labels to an entity by qualified name
      effect: write
      questions:
      - Is there a way to append labels when I only have a type name and qualifiedName?
      - What happens if I send an empty label list when adding labels by unique attribute?
      instructions:
      - text: Find the {type_name} with qualified name {qualified_name} and append labels to it.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Append labels to the {type_name} asset named {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/labels'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace labels on an entity by qualified name
      effect: write
      questions:
      - Does setting an empty label list clear all labels on an entity found by qualifiedName?
      - How do I overwrite labels on an asset by type and unique attribute?
      instructions:
      - text: Set labels on {type_name} entity {qualified_name}, replacing existing ones.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Overwrite the labels of the {type_name} asset {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/entity/uniqueAttribute/type/{typeName}/labels'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete labels from an entity by qualified name
      effect: destructive
      questions:
      - Are unknown labels ignored when I delete labels from an entity by qualifiedName?
      - How do I remove labels from an asset I identify by type and unique attribute?
      instructions:
      - text: Delete labels from {type_name} entity {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      - text: Remove the given labels from the {type_name} asset named {qualified_name}.
        slots:
          type_name: path.typeName
          qualified_name: query.attr:qualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/entity/bulk/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete entities along with their hierarchy
      effect: destructive
      questions:
      - Can I delete entities together with everything beneath them in the hierarchy?
      - Is there a way to control how many deletions run in parallel for a hierarchy delete?
      instructions:
      - text: Delete entities {guids} and their child hierarchy.
        slots:
          guids: query.guid
      - text: Remove {guids} with hierarchy using {parallel_count} parallel workers.
        slots:
          guids: query.guid
          parallel_count: query.parallelCount
      method: generated
      generated: '2026-09-26'
- target: $.paths['/entity/operations/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check status of a long-running entity operation
      effect: read
      questions:
      - How do I find out whether a long-running entity job has finished?
      - What's the status of a background entity operation I started?
      instructions:
      - text: Get the status of entity operation {operation_id}.
        slots:
          operation_id: path.operationId
      - text: Check whether entity job {operation_id} is done.
        slots:
          operation_id: path.operationId
      method: generated
      generated: '2026-09-26'