# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Applications.application API
  version: 1.0.0
extends: openapi/azure-ad-applications-application-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['/applications'].get
  update:
    x-apievangelist-phrasing:
      intent: List app registrations in the organization
      effect: read
      questions:
      - Which app registrations exist in our Microsoft Entra tenant?
      - Does the applications list include agent identity blueprints too?
      instructions:
      - text: List all application registrations in the tenant.
      - text: Show the app registrations matching the OData filter {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new application
      effect: write
      questions:
      - How do I register a new app in Microsoft Entra ID through the API?
      - Can I set the sign-in audience and redirect URIs when I create an app registration?
      instructions:
      - text: Register a new application called {displayName}.
        slots:
          displayName: requestBody.displayName
      - text: Create app registration {displayName} with sign-in audience {audience}.
        slots:
          displayName: requestBody.displayName
          audience: requestBody.signInAudience
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app registration by object ID
      effect: read
      questions:
      - How do I read an app registration's properties using its object ID?
      - Can I fetch an agent identity blueprint the same way as an application by ID?
      instructions:
      - text: Get application object {application}.
        slots:
          application: path.application-id
      - text: Show the redirect URIs and credentials on app registration object {application}.
        slots:
          application: path.application-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app registration by object ID
      effect: destructive
      questions:
      - How do I delete an app registration when I have its object ID?
      - Can a deleted application be restored, and for how long?
      instructions:
      - text: Delete application object {application}.
        slots:
          application: path.application-id
      - text: Move app registration object {application} to deleted items if its ETag matches {etag}.
        slots:
          application: path.application-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update or create an app registration by object ID
      effect: write
      questions:
      - How do I change the display name of an app registration using its object ID?
      - Can I add required API permissions to an existing application object?
      instructions:
      - text: Rename application object {application} to {displayName}.
        slots:
          application: path.application-id
          displayName: requestBody.displayName
      - text: Set the required resource access on application object {application} to {access}.
        slots:
          application: path.application-id
          access: requestBody.requiredResourceAccess
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}/logo'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an application's logo
      effect: read
      questions:
      - How do I download the main logo image of an app registration?
      - Can I retrieve the logo shown for an application in the directory?
      instructions:
      - text: Download the logo of application {application}.
        slots:
          application: path.application-id
      - text: Get the main logo image for app registration {application}.
        slots:
          application: path.application-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}/logo'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload an application's logo
      effect: write
      questions:
      - How do I upload a new logo for an app registration?
      - Can I replace the existing logo image on an application?
      instructions:
      - text: Upload a new logo for application {application}.
        slots:
          application: path.application-id
      - text: Replace the logo image on app registration {application}.
        slots:
          application: path.application-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/{application-id}/logo'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an application's logo
      effect: destructive
      questions:
      - How do I remove the logo from an app registration?
      - Can I clear an application's logo image entirely?
      instructions:
      - text: Remove the logo from application {application}.
        slots:
          application: path.application-id
      - text: Delete the logo image on app registration {application} if its ETag is {etag}.
        slots:
          application: path.application-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(appId=\'{appId}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app registration by its client (app) ID
      effect: read
      questions:
      - Can I look up an app registration by its client ID instead of the object ID?
      - How do I find the application that owns a given appId?
      instructions:
      - text: Get the application with client ID {appId}.
        slots:
          appId: path.appId
      - text: Look up the app registration whose appId is {appId}.
        slots:
          appId: path.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(appId=\'{appId}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app registration by its client (app) ID
      effect: destructive
      questions:
      - How do I delete an app registration when all I have is its client ID?
      - Can I remove an application by appId rather than object ID?
      instructions:
      - text: Delete the application with client ID {appId}.
        slots:
          appId: path.appId
      - text: Remove the app registration addressed by appId {appId} if its ETag is {etag}.
        slots:
          appId: path.appId
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(appId=\'{appId}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update or create an app registration by client ID
      effect: write
      questions:
      - How do I update an app registration addressed by its client ID?
      - Can I upsert an application keyed on appId so it's created if missing?
      instructions:
      - text: Rename the application with client ID {appId} to {displayName}.
        slots:
          appId: path.appId
          displayName: requestBody.displayName
      - text: Set the sign-in audience of the app with appId {appId} to {audience}.
        slots:
          appId: path.appId
          audience: requestBody.signInAudience
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(uniqueName=\'{uniqueName}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app registration by its unique name
      effect: read
      questions:
      - Can I fetch an application using the unique name I assigned it?
      - How do I look up an app registration by uniqueName?
      instructions:
      - text: Get the application with unique name {uniqueName}.
        slots:
          uniqueName: path.uniqueName
      - text: Look up the app registration keyed by uniqueName {uniqueName}.
        slots:
          uniqueName: path.uniqueName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(uniqueName=\'{uniqueName}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app registration by its unique name
      effect: destructive
      questions:
      - How do I delete an application identified by its unique name?
      - Can I remove an app registration by uniqueName instead of object ID?
      instructions:
      - text: Delete the application with unique name {uniqueName}.
        slots:
          uniqueName: path.uniqueName
      - text: Remove the app registration keyed by uniqueName {uniqueName} if its ETag is {etag}.
        slots:
          uniqueName: path.uniqueName
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications(uniqueName=\'{uniqueName}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Upsert an app registration by its unique name
      effect: write
      questions:
      - How do I create an application if it doesn't exist, keyed on a unique name?
      - Can I idempotently update an app registration by its uniqueName?
      instructions:
      - text: Upsert the application with unique name {uniqueName} and display name {displayName}.
        slots:
          uniqueName: path.uniqueName
          displayName: requestBody.displayName
      - text: Set identifier URIs {uris} on the app keyed by uniqueName {uniqueName}, creating it if missing.
        slots:
          uniqueName: path.uniqueName
          uris: requestBody.identifierUris
      method: generated
      generated: '2026-10-01'
- target: $.paths['/applications/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count app registrations
      effect: read
      questions:
      - How many app registrations does our tenant have?
      - What's the total number of applications in the directory?
      instructions:
      - text: Count the application registrations in the tenant.
      - text: Tell me how many apps are registered in our directory.
      method: generated
      generated: '2026-10-01'