# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Applications Service Principals.service Principal API
  version: 1.0.0
extends: openapi/azure-ad-serviceprincipals-serviceprincipal-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: 9
- target: $.paths['/servicePrincipals'].get
  update:
    x-apievangelist-phrasing:
      intent: List service principals
      effect: read
      questions:
      - Which enterprise apps and service principals exist in my tenant?
      - Does listing service principals also return agent identity blueprint principals?
      - Can I search service principals by display name?
      instructions:
      - text: List all service principals in the tenant.
      - text: Find service principals whose name matches {search}.
        slots:
          search: query.$search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a service principal
      effect: write
      questions:
      - How do I create a service principal for an app registration?
      - Can I create an agent identity blueprint principal the same way?
      instructions:
      - text: Create a service principal for application ID {appId}.
        slots:
          appId: requestBody.appId
      - text: Create a service principal for app {appId} requiring role assignment {appRoleAssignmentRequired}.
        slots:
          appId: requestBody.appId
          appRoleAssignmentRequired: requestBody.appRoleAssignmentRequired
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service principal by object ID
      effect: read
      questions:
      - How can I read a service principal when I have its object ID?
      - What properties and relationships does an enterprise app's service principal expose?
      instructions:
      - text: Get service principal with object ID {servicePrincipal}.
        slots:
          servicePrincipal: path.servicePrincipal-id
      - text: Show service principal {servicePrincipal} with its {expand} expanded.
        slots:
          servicePrincipal: path.servicePrincipal-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a service principal by object ID
      effect: destructive
      questions:
      - Can I delete an enterprise app's service principal using its object ID?
      - Does removing a service principal by object ID also work for agent identity blueprint principals?
      instructions:
      - text: Delete service principal object {servicePrincipal}.
        slots:
          servicePrincipal: path.servicePrincipal-id
      - text: Remove the enterprise app whose service principal object ID is {servicePrincipal}.
        slots:
          servicePrincipal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Upsert a service principal by object ID
      effect: write
      questions:
      - How do I update a service principal's settings given its object ID?
      - Can I disable sign-in for an enterprise app by its object ID?
      instructions:
      - text: Set accountEnabled to {accountEnabled} on service principal object {servicePrincipal}.
        slots:
          servicePrincipal: path.servicePrincipal-id
          accountEnabled: requestBody.accountEnabled
      - text: Add tags {tags} to the service principal with object ID {servicePrincipal}.
        slots:
          servicePrincipal: path.servicePrincipal-id
          tags: requestBody.tags
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals(appId=\'{appId}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service principal by its app ID
      effect: read
      questions:
      - Can I look up a service principal using the application (client) ID instead of the object ID?
      - Which service principal belongs to a given client ID?
      instructions:
      - text: Get the service principal for client ID {appId}.
        slots:
          appId: path.appId
      - text: Look up the enterprise app by application ID {appId}.
        slots:
          appId: path.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals(appId=\'{appId}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a service principal by its app ID
      effect: destructive
      questions:
      - Can I delete a service principal knowing only its application client ID?
      - Is there a way to remove an enterprise app by appId rather than object ID?
      instructions:
      - text: Delete the service principal for client ID {appId}.
        slots:
          appId: path.appId
      - text: Remove the enterprise app tied to application ID {appId}.
        slots:
          appId: path.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals(appId=\'{appId}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Upsert a service principal by its app ID
      effect: write
      questions:
      - Can I create a service principal if missing, or update it, addressed by appId?
      - What's the idempotent way to make sure an app ID has a service principal?
      instructions:
      - text: Upsert the service principal for client ID {appId}.
        slots:
          appId: path.appId
      - text: Ensure application ID {appId} has a service principal with display name {displayName}.
        slots:
          appId: path.appId
          displayName: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count service principals
      effect: read
      questions:
      - How many service principals does my tenant have?
      - Can I count only the service principals that match a filter?
      instructions:
      - text: Count the service principals in the directory.
      - text: Tell me how many service principals match {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'