API Evangelist conversational phrasing for GitHub v3 REST Apps API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST Apps API
  version: 1.0.0
extends: openapi/github-apps-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 29
- target: $.paths['/app'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the GitHub App I'm authenticated as
      effect: read
      questions:
      - Which GitHub App do my current JWT credentials belong to?
      - Can I confirm my app's name and owner from its own credentials?
      instructions:
      - text: Show the app associated with my current app credentials.
      - text: Tell me which app I am authenticated as right now.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app-manifests/{code}/conversions'].post
  update:
    x-apievangelist-phrasing:
      intent: Finish creating an app from a manifest
      effect: write
      questions:
      - How do I complete the app manifest flow after the user is redirected back with a code?
      - What do I get back when I exchange a manifest code for a new app?
      instructions:
      - text: Convert manifest code {code} into a new app and return its credentials.
        slots:
          code: path.code
      - text: Complete the app manifest handshake using temporary code {code}.
        slots:
          code: path.code
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/hook/config'].get
  update:
    x-apievangelist-phrasing:
      intent: View my app's webhook configuration
      effect: read
      questions:
      - Where is my app sending its webhook payloads?
      - What content type and SSL setting is my app's webhook using?
      instructions:
      - text: Show my app's webhook configuration.
      - text: Get the current webhook URL and content type for my app.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/hook/config'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change my app's webhook settings
      effect: write
      questions:
      - Can I point my app's webhook at a new URL?
      - How do I rotate the secret used to sign my app's webhook deliveries?
      instructions:
      - text: Change my app's webhook URL to {url}.
        slots:
          url: requestBody.url
      - text: Set my app's webhook secret to {secret} and content type to {content_type}.
        slots:
          secret: requestBody.secret
          content_type: requestBody.content_type
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/hook/deliveries'].get
  update:
    x-apievangelist-phrasing:
      intent: List my app's webhook deliveries
      effect: read
      questions:
      - Which webhook deliveries has my app sent recently?
      - Can I see only the redelivered webhook attempts for my app?
      instructions:
      - text: List recent webhook deliveries for my app.
      - text: Show my app's webhook deliveries starting from cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/hook/deliveries/{delivery_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect one webhook delivery for my app
      effect: read
      questions:
      - What request and response were recorded for one of my app's webhook deliveries?
      - Why did a particular webhook delivery to my app fail?
      instructions:
      - text: Show webhook delivery {delivery_id} for my app.
        slots:
          delivery_id: path.delivery_id
      - text: Get the payload and response status of app delivery {delivery_id}.
        slots:
          delivery_id: path.delivery_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/hook/deliveries/{delivery_id}/attempts'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeliver a webhook from my app
      effect: write
      questions:
      - Can I resend a webhook my app already delivered once?
      - How do I retry a failed webhook delivery for my app?
      instructions:
      - text: Redeliver webhook delivery {delivery_id} for my app.
        slots:
          delivery_id: path.delivery_id
      - text: Retry sending app webhook delivery {delivery_id} again.
        slots:
          delivery_id: path.delivery_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installation-requests'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending installation requests for my app
      effect: read
      questions:
      - Who has asked to install my app but is still waiting for approval?
      - Are there any pending installation requests for my app?
      instructions:
      - text: List pending installation requests for my app.
      - text: Show outstanding install requests awaiting approval, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations'].get
  update:
    x-apievangelist-phrasing:
      intent: List my app's installations
      effect: read
      questions:
      - Which accounts have installed my GitHub App?
      - Can I see only the installations updated since a certain date?
      - What permissions does each installation of my app have?
      instructions:
      - text: List every installation of my app.
      - text: Show my app's installations updated since {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations/{installation_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one installation of my app
      effect: read
      questions:
      - What account and permissions belong to a given installation ID?
      - Can I look up a single installation of my app by its ID?
      instructions:
      - text: Get installation {installation_id} of my app.
        slots:
          installation_id: path.installation_id
      - text: Show the account and permissions for app installation {installation_id}.
        slots:
          installation_id: path.installation_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations/{installation_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Uninstall my app from an account
      effect: destructive
      questions:
      - How do I completely uninstall my app from an organization or user account?
      - What's the difference between uninstalling and suspending an app installation?
      instructions:
      - text: Uninstall my app from installation {installation_id}.
        slots:
          installation_id: path.installation_id
      - text: Permanently remove app installation {installation_id}.
        slots:
          installation_id: path.installation_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations/{installation_id}/access_tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an installation access token
      effect: write
      questions:
      - How do I get a token so my app can call the API on behalf of an installation?
      - Can I limit an installation token to just a few repositories?
      - How long does an installation access token last?
      instructions:
      - text: Create an access token for installation {installation_id}.
        slots:
          installation_id: path.installation_id
      - text: Mint an installation token for {installation_id} limited to repositories {repositories}.
        slots:
          installation_id: path.installation_id
          repositories: requestBody.repositories
      - text: Generate a token for installation {installation_id} with only permissions {permissions}.
        slots:
          installation_id: path.installation_id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations/{installation_id}/suspended'].put
  update:
    x-apievangelist-phrasing:
      intent: Suspend an app installation
      effect: destructive
      questions:
      - Can I temporarily block my app from an account without uninstalling it?
      - What stops working when an app installation is suspended?
      instructions:
      - text: Suspend app installation {installation_id}.
        slots:
          installation_id: path.installation_id
      - text: Block installation {installation_id} from accessing the account's resources for now.
        slots:
          installation_id: path.installation_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/app/installations/{installation_id}/suspended'].delete
  update:
    x-apievangelist-phrasing:
      intent: Lift a suspension on an app installation
      effect: destructive
      questions:
      - How do I restore access for an app installation I suspended?
      - Can a suspended installation be reactivated?
      instructions:
      - text: Unsuspend app installation {installation_id}.
        slots:
          installation_id: path.installation_id
      - text: Restore access for suspended installation {installation_id}.
        slots:
          installation_id: path.installation_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/{client_id}/grant'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's grant for my app
      effect: destructive
      questions:
      - How can I revoke every token a user has for my OAuth app?
      - Can an app owner delete a user's authorization grant?
      instructions:
      - text: Revoke the grant for my app {client_id} tied to access token {access_token}.
        slots:
          client_id: path.client_id
          access_token: requestBody.access_token
      - text: Delete the user authorization behind token {access_token} for app client {client_id}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/{client_id}/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether an OAuth token is valid
      effect: read
      questions:
      - Can I verify a user's OAuth token without using up their rate limit?
      - Is a given access token still valid for my app?
      instructions:
      - text: Check if token {access_token} is valid for app {client_id}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      - text: Validate OAuth token {access_token} against my app client {client_id}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/{client_id}/token'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a single OAuth token
      effect: destructive
      questions:
      - How do I revoke just one user token for my OAuth app?
      - Can I invalidate a leaked access token without revoking the whole grant?
      instructions:
      - text: Revoke access token {access_token} for app {client_id}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      - text: Invalidate the single token {access_token} issued by app client {client_id}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/{client_id}/token'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's OAuth token
      effect: write
      questions:
      - Can I swap a user's OAuth token for a new one without them re-authorizing?
      - What happens to the old token when I reset it?
      instructions:
      - text: Reset token {access_token} for app {client_id} and give me the new one.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      - text: Rotate user token {access_token} on app client {client_id} without user involvement.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/{client_id}/token/scoped'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a narrower, scoped user access token
      effect: write
      questions:
      - Can I turn a broad user access token into one limited to certain repositories?
      - How do I restrict a user token to one organization and a smaller permission set?
      instructions:
      - text: Scope token {access_token} for app {client_id} to account {target}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
          target: requestBody.target
      - text: Create a scoped copy of {access_token} for app {client_id} limited to repositories {repositories}.
        slots:
          access_token: requestBody.access_token
          client_id: path.client_id
          repositories: requestBody.repositories
      method: generated
      generated: '2026-09-24'
- target: $.paths['/apps/{app_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an app by its slug
      effect: read
      questions:
      - Can I get public details about an app from its URL-friendly name?
      - Where do I find an app's slug to look it up?
      instructions:
      - text: Get the app with slug {app_slug}.
        slots:
          app_slug: path.app_slug
      - text: Show public information for the {app_slug} app.
        slots:
          app_slug: path.app_slug
      method: generated
      generated: '2026-09-24'
- target: $.paths['/installation/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List repos this installation token can access
      effect: read
      questions:
      - Which repositories can my app installation reach with its current token?
      - What repos does this installation have access to?
      instructions:
      - text: List the repositories accessible to this installation.
      - text: Show repos my installation token can reach, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/installation/token'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke the installation token I'm using
      effect: destructive
      questions:
      - Can I kill the installation token I'm currently authenticated with before it expires?
      - What happens after an installation token revokes itself?
      instructions:
      - text: Revoke the installation access token I'm using now.
      - text: Invalidate my current installation token immediately.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/installation'].get
  update:
    x-apievangelist-phrasing:
      intent: Find my app's installation on an organization
      effect: read
      questions:
      - Is my app installed on a given organization, and under which installation ID?
      - How do I find the installation for an org from my app?
      instructions:
      - text: Get my app's installation on organization {org}.
        slots:
          org: path.org
      - text: Find the installation ID for my app in the {org} org.
        slots:
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/installation'].get
  update:
    x-apievangelist-phrasing:
      intent: Find my app's installation for a repository
      effect: read
      questions:
      - Which installation of my app covers a particular repository?
      - Is my app installed on a given repo?
      instructions:
      - text: Get my app's installation for {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Find which installation of my app includes repository {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/installations'].get
  update:
    x-apievangelist-phrasing:
      intent: List app installations I can access as a user
      effect: read
      questions:
      - Which installations of this app does the signed-in user have permission to access?
      - Can I see the app installations available to a user access token?
      instructions:
      - text: List the app installations my user token can access.
      - text: Show installations I have read, write or admin access to, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/installations/{installation_id}/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List repos I can access in an installation
      effect: read
      questions:
      - Which repositories in an installation does the signed-in user have access to?
      - Can I list repos for one installation using a user access token?
      instructions:
      - text: List repositories I can access in installation {installation_id}.
        slots:
          installation_id: path.installation_id
      - text: Show the repos my user token can reach through installation {installation_id}.
        slots:
          installation_id: path.installation_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/installations/{installation_id}/repositories/{repository_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a repository to an app installation
      effect: write
      questions:
      - How do I give an installed app access to one more repository?
      - What access do I need on a repo to add it to an installation?
      instructions:
      - text: Add repository {repository_id} to installation {installation_id}.
        slots:
          repository_id: path.repository_id
          installation_id: path.installation_id
      - text: Grant installation {installation_id} access to repo ID {repository_id}.
        slots:
          installation_id: path.installation_id
          repository_id: path.repository_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/installations/{installation_id}/repositories/{repository_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a repository from an app installation
      effect: destructive
      questions:
      - Can I take a single repository away from an installed app?
      - Which token type is required to remove a repo from an installation?
      instructions:
      - text: Remove repository {repository_id} from installation {installation_id}.
        slots:
          repository_id: path.repository_id
          installation_id: path.installation_id
      - text: Revoke installation {installation_id}'s access to repo ID {repository_id}.
        slots:
          installation_id: path.installation_id
          repository_id: path.repository_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/installation'].get
  update:
    x-apievangelist-phrasing:
      intent: Find my app's installation on a user account
      effect: read
      questions:
      - Has a particular user installed my app on their personal account?
      - How can my app find the installation for a given username?
      instructions:
      - text: Look up the personal-account installation of my app belonging to user {username}.
        slots:
          username: path.username
      - text: Find the installation ID of my app on {username}'s account.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'