Microsoft Entra ID (formerly Azure AD) · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Identity.Governance Agreements.agreement File API

16 actions 16 updates phrasing extends openapi/azure-ad-agreements-agreementfile-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Microsoft Entra ID (formerly Azure AD)'s API. It is a proposal applied on top of the contract, not a document Microsoft Entra ID (formerly Azure AD) publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 16

$.info

$.paths['/agreements/{agreement-id}/file'].get

$.paths['/agreements/{agreement-id}/file'].delete

$.paths['/agreements/{agreement-id}/file'].patch

$.paths['/agreements/{agreement-id}/file/localizations'].get

$.paths['/agreements/{agreement-id}/file/localizations'].post

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].get

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].delete

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].patch

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions'].get

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions'].post

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].get

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].delete

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].patch

$.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/$count'].get

$.paths['/agreements/{agreement-id}/file/localizations/$count'].get

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.Governance Agreements.agreement File API
  version: 1.0.0
extends: openapi/azure-ad-agreements-agreementfile-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: 15
- target: $.paths['/agreements/{agreement-id}/file'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a terms of use agreement's default file
      effect: read
      questions:
      - How do I see the default file attached to a terms of use agreement, including its language?
      - Which version of the default agreement file is currently in place?
      instructions:
      - text: Get the default agreement file for agreement {agreement}.
        slots:
          agreement: path.agreement-id
      - text: Show language and version details of the file on agreement {agreement}.
        slots:
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an agreement's default file
      effect: destructive
      questions:
      - Can I remove the default file from a terms of use agreement?
      - What deletes the file property of an agreement without deleting the agreement?
      instructions:
      - text: Delete the default file from agreement {agreement}.
        slots:
          agreement: path.agreement-id
      - text: Remove the agreement file on {agreement} if its ETag matches {etag}.
        slots:
          agreement: path.agreement-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an agreement's default file
      effect: write
      questions:
      - Can I replace the localizations on an agreement's default file?
      - Is it possible to patch the file object on a terms of use agreement?
      instructions:
      - text: Update the default file on agreement {agreement} with localizations {localizations}.
        slots:
          agreement: path.agreement-id
          localizations: requestBody.localizations
      - text: Patch the file object attached to agreement {agreement}.
        slots:
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List an agreement file's language versions
      effect: read
      questions:
      - Which languages is our terms of use agreement file available in?
      - Can I list both the default and localized files for an agreement?
      instructions:
      - text: List the default and localized files for agreement {agreement}.
        slots:
          agreement: path.agreement-id
      - text: List localizations of agreement {agreement} matching {filter}.
        slots:
          agreement: path.agreement-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a localized agreement file
      effect: write
      questions:
      - How do I add another language version of an agreement file?
      - Can I create a localization with its versions already attached?
      instructions:
      - text: Add a new localization to the file of agreement {agreement}.
        slots:
          agreement: path.agreement-id
      - text: Create a localized file on agreement {agreement} with versions {versions}.
        slots:
          agreement: path.agreement-id
          versions: requestBody.versions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one localized agreement file
      effect: read
      questions:
      - What does a specific language version of our terms of use file contain?
      - Is a given localized agreement file the default one?
      instructions:
      - text: Get localization {localization} of agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Show the localized file {localization} on agreement {agreement} with only {fields}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
          fields: query.$select
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a localized agreement file
      effect: destructive
      questions:
      - Can I remove one language version from a terms of use agreement?
      - How do I delete a localized file without touching the default file?
      instructions:
      - text: Delete localization {localization} from agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Remove the localized agreement file {localization} from {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a localized agreement file
      effect: write
      questions:
      - Can I change the versions list on a localized agreement file?
      - Is it possible to patch one language version of an agreement file?
      instructions:
      - text: Update localization {localization} on agreement {agreement} with versions {versions}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
          versions: requestBody.versions
      - text: Patch the localized file {localization} of agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of a localized agreement file
      effect: read
      questions:
      - What earlier versions exist for one language of our terms of use file?
      - Can I page through the version history of a localized agreement file?
      instructions:
      - text: List versions of localization {localization} on agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: List the first {count} versions of localized file {localization} on agreement {agreement}.
        slots:
          count: query.$top
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a version to a localized agreement file
      effect: write
      questions:
      - Can I add a new version under a localized agreement file?
      - Is there a way to create a customized version for one language of our terms of use?
      instructions:
      - text: Create a new version under localization {localization} of agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Add a version entry to the localized file {localization} on agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one version of a localized agreement file
      effect: read
      questions:
      - What did a specific past version of a localized terms of use file look like?
      - Where do I read one version record of an agreement localization?
      instructions:
      - text: Get version {version} of localization {localization} on agreement {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Show agreement file version {version} for localization {localization} of {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a version of a localized agreement file
      effect: destructive
      questions:
      - Can I delete an old version of a localized agreement file?
      - How do I remove a single version from a localization's history?
      instructions:
      - text: Delete version {version} from localization {localization} on agreement {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Remove file version {version} of localized file {localization} in agreement {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/{agreementFileVersion-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a version of a localized agreement file
      effect: write
      questions:
      - Can an existing version of a localized agreement file be patched?
      - Is there an update call for one version record under an agreement localization?
      instructions:
      - text: Update version {version} of localization {localization} on agreement {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Patch file version {version} under localized file {localization} of {agreement}.
        slots:
          version: path.agreementFileVersion-id
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/{agreementFileLocalization-id}/versions/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count versions of a localized agreement file
      effect: read
      questions:
      - How many versions exist for one language of an agreement file?
      - Can I count only the localization versions that match a filter?
      instructions:
      - text: Count versions of localization {localization} on agreement {agreement}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
      - text: Count versions of localized file {localization} in agreement {agreement} matching {filter}.
        slots:
          localization: path.agreementFileLocalization-id
          agreement: path.agreement-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agreements/{agreement-id}/file/localizations/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count an agreement file's localizations
      effect: read
      questions:
      - How many language versions does our terms of use agreement file have?
      - Can I count agreement localizations matching a search?
      instructions:
      - text: Count the localizations on agreement {agreement}.
        slots:
          agreement: path.agreement-id
      - text: Count localized files of agreement {agreement} that match {filter}.
        slots:
          agreement: path.agreement-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'