# 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 Glossary API
  version: 1.0.0
extends: openapi/microsoft-purview-glossary-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/glossary'].get
  update:
    x-apievangelist-phrasing:
      intent: List all glossaries
      effect: read
      questions:
      - What business glossaries exist in our Purview catalog?
      - Can I list glossaries without loading their terms and categories?
      instructions:
      - text: List all glossaries.
      - text: List glossaries {limit} at a time starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      - text: 'List glossaries without terms and categories: {ignore}.'
        slots:
          ignore: query.ignoreTermsAndCategories
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a glossary
      effect: write
      questions:
      - How do I start a new business glossary?
      - Can I give a glossary a short and long description when I create it?
      instructions:
      - text: Create a glossary named {name}.
        slots:
          name: requestBody.name
      - text: Create glossary {name} with short description {short}.
        slots:
          name: requestBody.name
          short: requestBody.shortDescription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/{glossaryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary
      effect: read
      questions:
      - Where can I see the details of one glossary by its GUID?
      - What language and usage notes does a glossary have?
      instructions:
      - text: Show me glossary {glossary}.
        slots:
          glossary: path.glossaryId
      - text: Get the details of glossary {glossary}.
        slots:
          glossary: path.glossaryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/{glossaryId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a glossary
      effect: write
      questions:
      - How do I rename a glossary or change its description?
      - Can I edit the usage guidance on an existing glossary?
      instructions:
      - text: Rename glossary {glossary} to {name}.
        slots:
          glossary: path.glossaryId
          name: requestBody.name
      - text: Set the long description of glossary {glossary} to {long}.
        slots:
          glossary: path.glossaryId
          long: requestBody.longDescription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/{glossaryId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a glossary with its terms
      effect: destructive
      questions:
      - Does deleting a glossary also remove its terms and categories?
      - Can I delete an entire glossary?
      instructions:
      - text: Delete glossary {glossary} and everything in it.
        slots:
          glossary: path.glossaryId
      - text: Remove glossary {glossary}.
        slots:
          glossary: path.glossaryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/{glossaryId}/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: List the terms in a glossary
      effect: read
      questions:
      - What terms belong to a particular glossary?
      - Can I page and sort the terms of one glossary?
      instructions:
      - text: List the terms in glossary {glossary}.
        slots:
          glossary: path.glossaryId
      - text: List {limit} terms of glossary {glossary} sorted {sort}.
        slots:
          limit: query.limit
          glossary: path.glossaryId
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/{glossaryId}/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List the categories in a glossary
      effect: read
      questions:
      - What categories organise the terms in a glossary?
      - Can I page through the categories of one glossary?
      instructions:
      - text: List the categories in glossary {glossary}.
        slots:
          glossary: path.glossaryId
      - text: List {limit} categories of glossary {glossary}.
        slots:
          limit: query.limit
          glossary: path.glossaryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/term'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a glossary term
      effect: write
      questions:
      - How do I add a single business term to a glossary?
      - Can I give a new term an abbreviation and a status?
      instructions:
      - text: Create a glossary term {name} anchored to glossary {anchor}.
        slots:
          name: requestBody.name
          anchor: requestBody.anchor
      - text: Add term {name} with abbreviation {abbr} and status {status}.
        slots:
          name: requestBody.name
          abbr: requestBody.abbreviation
          status: requestBody.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/term/{termId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary term
      effect: read
      questions:
      - What is the definition of a specific glossary term?
      - Which assets and categories is one term linked to?
      instructions:
      - text: Show me glossary term {term}.
        slots:
          term: path.termId
      - text: Get the definition of term {term}.
        slots:
          term: path.termId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/term/{termId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a glossary term
      effect: write
      questions:
      - How do I edit the definition of an existing glossary term?
      - Can I change a term's status from draft to approved?
      instructions:
      - text: Set the status of glossary term {term} to {status}.
        slots:
          term: path.termId
          status: requestBody.status
      - text: Update the long description of existing term {term} to {long}.
        slots:
          term: path.termId
          long: requestBody.longDescription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/term/{termId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a glossary term
      effect: destructive
      questions:
      - Can I remove a single term from a glossary?
      - What is the way to delete an obsolete glossary term?
      instructions:
      - text: Delete glossary term {term}.
        slots:
          term: path.termId
      - text: Remove term {term} from its glossary.
        slots:
          term: path.termId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/terms'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many glossary terms at once
      effect: write
      questions:
      - Can I import a batch of glossary terms in one request?
      - Is there a bulk way to add terms to a glossary?
      instructions:
      - text: Create these glossary terms in bulk.
      - text: Bulk import a list of terms into the glossary.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/category'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a glossary category
      effect: write
      questions:
      - How do I add a category to group glossary terms?
      - Can a new category be nested under a parent category?
      instructions:
      - text: Create a glossary category {name} in glossary {anchor}.
        slots:
          name: requestBody.name
          anchor: requestBody.anchor
      - text: Add category {name} under parent category {parent}.
        slots:
          name: requestBody.name
          parent: requestBody.parentCategory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/category/{categoryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a glossary category
      effect: read
      questions:
      - Which terms and child categories sit inside a glossary category?
      - Where can I see one category by its GUID?
      instructions:
      - text: Show me glossary category {category}.
        slots:
          category: path.categoryId
      - text: Get the terms and children of category {category}.
        slots:
          category: path.categoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/category/{categoryId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a glossary category
      effect: write
      questions:
      - How do I rename a glossary category?
      - Can I move a category under a different parent?
      instructions:
      - text: Rename glossary category {category} to {name}.
        slots:
          category: path.categoryId
          name: requestBody.name
      - text: Move category {category} under parent {parent}.
        slots:
          category: path.categoryId
          parent: requestBody.parentCategory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/category/{categoryId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a glossary category
      effect: destructive
      questions:
      - Can I delete a category from a glossary?
      - What is the way to remove an unused glossary category?
      instructions:
      - text: Delete glossary category {category}.
        slots:
          category: path.categoryId
      - text: Remove category {category}.
        slots:
          category: path.categoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/terms/{termId}/assignedEntities'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets tagged with a glossary term
      effect: read
      questions:
      - Which data assets have a particular glossary term assigned?
      - Can I page through the entities linked to a term?
      instructions:
      - text: List the assets assigned glossary term {term}.
        slots:
          term: path.termId
      - text: Show {limit} entities tagged with term {term}.
        slots:
          limit: query.limit
          term: path.termId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/terms/{termId}/assignedEntities'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a glossary term to assets
      effect: write
      questions:
      - How do I tag data assets with a business glossary term?
      - Can I link one term to several entities at once?
      instructions:
      - text: Assign glossary term {term} to the given assets.
        slots:
          term: path.termId
      - text: Tag these entities with term {term}.
        slots:
          term: path.termId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/atlas/v2/glossary/terms/{termId}/assignedEntities'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unassign a glossary term from assets
      effect: destructive
      questions:
      - How do I remove a glossary term from assets it was assigned to?
      - Can I unlink a term from specific entities?
      instructions:
      - text: Remove the assignment of term {term} from the given assets.
        slots:
          term: path.termId
      - text: Untag these entities from glossary term {term}.
        slots:
          term: path.termId
      method: generated
      generated: '2026-10-01'