# 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 Glossary API
  version: 1.0.0
extends: openapi/microsoft-azure-glossary-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: 39
- target: $.paths['/atlas/v2/glossary'].get
  update:
    x-apievangelist-phrasing:
      intent: List all business glossaries
      effect: read
      questions:
      - Which glossaries are registered in my Purview data catalog?
      - Can I page through every glossary without pulling all their terms and categories?
      instructions:
      - text: List all glossaries in the catalog.
      - text: List glossaries {limit} at a time starting at offset {offset}, skipping terms and categories.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new glossary
      effect: write
      questions:
      - How do I create a new business glossary in Microsoft Purview?
      - Can I set a language and usage note when creating a glossary?
      instructions:
      - text: Create a new glossary in {language} with usage note {usage}.
        slots:
          language: requestBody.language
          usage: requestBody.usage
      - text: Set up a brand new empty glossary for our data catalog.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many glossary categories at once
      effect: write
      questions:
      - Can I create a batch of glossary categories in a single request?
      - What's the way to bulk-load a list of categories into a glossary?
      instructions:
      - text: Bulk-create these glossary categories in one call.
      - text: Create several glossary categories together from this list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a single glossary category
      effect: write
      questions:
      - How do I add one new category to a glossary?
      - Can a new glossary category be nested under a parent category?
      instructions:
      - text: Create a category in glossary {anchor}.
        slots:
          anchor: requestBody.anchor
      - text: Create a category in glossary {anchor} under parent category {parentCategory}.
        slots:
          anchor: requestBody.anchor
          parentCategory: requestBody.parentCategory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary category by GUID
      effect: read
      questions:
      - How can I look up a single glossary category by its GUID?
      - What details come back for one glossary category?
      instructions:
      - text: Show me glossary category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      - text: Fetch the full record for category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a glossary category
      effect: write
      questions:
      - How do I fully update an existing glossary category, including its child categories?
      - Can I move a glossary category to a different parent?
      instructions:
      - text: Update glossary category {categoryGuid} with a full replacement definition.
        slots:
          categoryGuid: path.categoryGuid
      - text: Set the parent of category {categoryGuid} to {parentCategory}.
        slots:
          categoryGuid: path.categoryGuid
          parentCategory: requestBody.parentCategory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a glossary category
      effect: destructive
      questions:
      - How do I remove a category from a glossary?
      - Is deleting a glossary category permanent?
      instructions:
      - text: Delete glossary category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      - text: Remove the category {categoryGuid} from the glossary.
        slots:
          categoryGuid: path.categoryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}/partial'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a category's descriptions only
      effect: write
      questions:
      - Can I change just the short or long description of a glossary category?
      - Which category fields can be updated partially?
      instructions:
      - text: Partially update the short and long description of category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      - text: Patch only the descriptions on glossary category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: List a category's parent and child categories
      effect: read
      questions:
      - What are the parent and child categories of a given glossary category?
      - Does paging work when listing related categories?
      instructions:
      - text: Show the parent and children of category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      - text: List categories related to {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/category/{categoryGuid}/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: List terms in a glossary category
      effect: read
      questions:
      - Which glossary terms are filed under a specific category?
      - Can I sort the terms in a category in descending order?
      instructions:
      - text: List the terms in category {categoryGuid}.
        slots:
          categoryGuid: path.categoryGuid
      - text: Get terms of category {categoryGuid} sorted {sort}.
        slots:
          categoryGuid: path.categoryGuid
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/term'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a single glossary term
      effect: write
      questions:
      - How do I add a new business term with synonyms and a steward contact?
      - Can I set an abbreviation and status when defining a term?
      instructions:
      - text: Create a glossary term in glossary {anchor} with abbreviation {abbreviation}.
        slots:
          anchor: requestBody.anchor
          abbreviation: requestBody.abbreviation
      - text: Add a new term to glossary {anchor} with status {status}.
        slots:
          anchor: requestBody.anchor
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/term/{termGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary term by GUID
      effect: read
      questions:
      - How do I look up one glossary term and its definition by GUID?
      - Can I exclude semantic assignment relationships when fetching a term?
      instructions:
      - text: Show glossary term {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Get term {termGuid} excluding relationship types {excludeRelationshipTypes}.
        slots:
          termGuid: path.termGuid
          excludeRelationshipTypes: query.excludeRelationshipTypes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/term/{termGuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a glossary term definition
      effect: write
      questions:
      - How do I fully update a glossary term, including its related terms?
      - Can I change a term's synonyms and experts in one update?
      instructions:
      - text: Replace the full definition of term {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Update term {termGuid} to use synonyms {synonyms}.
        slots:
          termGuid: path.termGuid
          synonyms: requestBody.synonyms
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/term/{termGuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one glossary term
      effect: destructive
      questions:
      - How do I delete a single term from a glossary?
      - What happens when I remove one glossary term by GUID?
      instructions:
      - text: Delete glossary term {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Remove the single term {termGuid} from its glossary.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/term/{termGuid}/partial'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit selected fields on a glossary term
      effect: write
      questions:
      - Can I change just a term's status or abbreviation without resending everything?
      - Which glossary term fields support a partial update?
      instructions:
      - text: Partially update the description, usage or status of term {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Patch only the abbreviation on glossary term {termGuid}.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many glossary terms at once
      effect: write
      questions:
      - Can I create a whole batch of glossary terms in one JSON request?
      - Is there a bulk endpoint for adding terms without a CSV file?
      instructions:
      - text: Bulk-create these glossary terms in one request.
      - text: Create several new terms together and include their term hierarchy.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms/{termGuid}/assignedEntities'].get
  update:
    x-apievangelist-phrasing:
      intent: List data assets tagged with a term
      effect: read
      questions:
      - Which data assets have a particular glossary term assigned?
      - Can I page through entities assigned to a term?
      instructions:
      - text: List assets assigned to term {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Show the first {limit} entities tagged with term {termGuid}.
        slots:
          limit: query.limit
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms/{termGuid}/assignedEntities'].put
  update:
    x-apievangelist-phrasing:
      intent: Unassign a term via the legacy PUT endpoint
      effect: destructive
      questions:
      - Is there an older PUT-based way to remove a term from data assets?
      - Why is the PUT endpoint for removing term assignments not recommended?
      instructions:
      - text: Use the legacy PUT endpoint to remove term {termGuid} from these assets.
        slots:
          termGuid: path.termGuid
      - text: Unassign term {termGuid} from the listed entities with the older PUT call.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms/{termGuid}/assignedEntities'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a term to data assets
      effect: write
      questions:
      - How do I tag a set of data assets with a glossary term?
      - Should I assign a term to entities in small batches?
      instructions:
      - text: Assign term {termGuid} to these data assets.
        slots:
          termGuid: path.termGuid
      - text: Tag the listed entities with glossary term {termGuid}.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms/{termGuid}/assignedEntities'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a term from data assets
      effect: destructive
      questions:
      - How do I untag data assets from a glossary term?
      - What is the recommended DELETE call for removing term assignments?
      instructions:
      - text: Delete the assignment of term {termGuid} from these assets.
        slots:
          termGuid: path.termGuid
      - text: Untag the listed entities from term {termGuid} using DELETE.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/terms/{termGuid}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: List terms related to a term
      effect: read
      questions:
      - What synonyms, antonyms and see-also terms are linked to a glossary term?
      - Which terms are related to a given term?
      instructions:
      - text: List terms related to {termGuid}.
        slots:
          termGuid: path.termGuid
      - text: Show the related-term links for glossary term {termGuid}.
        slots:
          termGuid: path.termGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary by GUID
      effect: read
      questions:
      - How do I fetch one glossary by its GUID?
      - What basic information does a single glossary record include?
      instructions:
      - text: Get glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Show the summary for glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a glossary's definition
      effect: write
      questions:
      - How do I fully update a glossary's language, usage and contents?
      - Can I update a glossary while ignoring its terms and categories?
      instructions:
      - text: Replace glossary {glossaryGuid} with the new definition.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Update glossary {glossaryGuid} usage to {usage}.
        slots:
          glossaryGuid: path.glossaryGuid
          usage: requestBody.usage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a glossary and its contents
      effect: destructive
      questions:
      - Does deleting a glossary also remove its terms and categories?
      - How do I delete an entire glossary?
      instructions:
      - text: Delete glossary {glossaryGuid} along with its terms and categories.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Remove the whole glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List categories in a glossary
      effect: read
      questions:
      - Which categories belong to a specific glossary?
      - Can I page through a glossary's full category records?
      instructions:
      - text: List the categories in glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Get {limit} full categories of glossary {glossaryGuid}.
        slots:
          limit: query.limit
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/categories/headers'].get
  update:
    x-apievangelist-phrasing:
      intent: List category headers in a glossary
      effect: read
      questions:
      - Can I get just the lightweight headers of a glossary's categories?
      - What's a quick way to list category names and GUIDs for a glossary?
      instructions:
      - text: List category headers for glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Show just the category names and GUIDs in glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/detailed'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary with full term and category detail
      effect: read
      questions:
      - Can I get a glossary with all its terms and categories expanded in one response?
      - Why is the detailed glossary endpoint discouraged?
      instructions:
      - text: Get the detailed view of glossary {glossaryGuid} with everything expanded.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Fetch glossary {glossaryGuid} including full term and category details.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/partial'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a glossary's description, language or usage
      effect: write
      questions:
      - Can I change only a glossary's language or usage text?
      - Which glossary properties can't be changed with a partial update?
      instructions:
      - text: Partially update the descriptions of glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Patch only the language and usage on glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: List terms in a glossary
      effect: read
      questions:
      - What terms are defined in a particular glossary?
      - Can I include the term hierarchy when listing a glossary's full terms?
      instructions:
      - text: List the terms in glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Get full terms from glossary {glossaryGuid} starting at offset {offset}.
        slots:
          glossaryGuid: path.glossaryGuid
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/atlas/v2/glossary/{glossaryGuid}/terms/headers'].get
  update:
    x-apievangelist-phrasing:
      intent: List term headers in a glossary
      effect: read
      questions:
      - Can I list just the names and GUIDs of terms in a glossary?
      - Is there a lighter-weight listing of glossary term headers?
      instructions:
      - text: List term headers for glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Show only term names and GUIDs in glossary {glossaryGuid}.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/{glossaryGuid}/terms/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import glossary terms from CSV
      effect: write
      questions:
      - How do I bulk import glossary terms from a CSV file?
      - Can a CSV import include multiple term templates?
      instructions:
      - text: Import terms from {file} into glossary {glossaryGuid}.
        slots:
          file: requestBody.file
          glossaryGuid: path.glossaryGuid
      - text: Upload CSV {file} to glossary {glossaryGuid} with multiple templates enabled.
        slots:
          file: requestBody.file
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/name/{glossaryName}/terms/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import CSV terms by glossary name (deprecated)
      effect: write
      questions:
      - Can I import a CSV of terms using the glossary's name instead of its GUID?
      - Is the import-by-glossary-name endpoint deprecated?
      instructions:
      - text: Import CSV {file} into the glossary named {glossaryName}.
        slots:
          file: requestBody.file
          glossaryName: path.glossaryName
      - text: Use the deprecated name-based import to load {file} into {glossaryName}.
        slots:
          file: requestBody.file
          glossaryName: path.glossaryName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/terms/import/{operationGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a CSV term import job
      effect: read
      questions:
      - How can I tell if my glossary CSV import has finished?
      - Did my term import job succeed or fail?
      instructions:
      - text: Check the status of CSV import {operationGuid}.
        slots:
          operationGuid: path.operationGuid
      - text: Tell me whether term import job {operationGuid} is done.
        slots:
          operationGuid: path.operationGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/{glossaryGuid}/terms/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export glossary terms to CSV
      effect: read
      questions:
      - How do I export a glossary's terms as a CSV file?
      - Can the CSV export keep rich text formatting?
      instructions:
      - text: Export the terms of glossary {glossaryGuid} to CSV.
        slots:
          glossaryGuid: path.glossaryGuid
      - text: Download glossary {glossaryGuid} terms as CSV with rich text included.
        slots:
          glossaryGuid: path.glossaryGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/name/{glossaryName}/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: List terms by glossary name (deprecated)
      effect: read
      questions:
      - Can I list terms by the glossary's name rather than its GUID?
      - Does listing terms by glossary name return contact display names?
      instructions:
      - text: List terms in the glossary named {glossaryName}.
        slots:
          glossaryName: path.glossaryName
      - text: Get terms for glossary name {glossaryName} with extended info.
        slots:
          glossaryName: path.glossaryName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/terms/bulkDeletion/{operationGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk term deletion job
      effect: read
      questions:
      - Has my bulk glossary term deletion finished?
      - Where do I see the progress of a bulk term delete?
      instructions:
      - text: Check the status of bulk delete {operationGuid}.
        slots:
          operationGuid: path.operationGuid
      - text: Tell me whether term deletion job {operationGuid} completed.
        slots:
          operationGuid: path.operationGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/terms:delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete glossary terms
      effect: destructive
      questions:
      - Can I delete many glossary terms at once?
      - Will a bulk term delete also remove child terms and entity assignments?
      instructions:
      - text: Bulk delete these glossary terms by GUID.
      - text: Delete the listed terms, forcing removal of child terms ({forceDeleteChild}).
        slots:
          forceDeleteChild: query.forceDeleteChild
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch several terms by their GUIDs
      effect: read
      questions:
      - Can I fetch several specific glossary terms in one call?
      - Is there a way to look up a batch of terms by GUID list?
      instructions:
      - text: Get the terms with GUIDs {guid}.
        slots:
          guid: query.guid
      - text: Look up this batch of term GUIDs {guid} at once.
        slots:
          guid: query.guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/glossary/terms'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many glossary terms at once
      effect: write
      questions:
      - Can I update a batch of glossary terms in a single call?
      - Is there a bulk edit endpoint for existing terms?
      instructions:
      - text: Bulk update these existing glossary terms.
      - text: Apply these edits to many terms in one request.
      method: generated
      generated: '2026-09-26'