# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snyk Apps API
  version: 1.0.0
extends: openapi/snyk-apps-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 28
- target: $.paths['/groups/{group_id}/apps/installs'].get
  update:
    x-apievangelist-phrasing:
      intent: List Snyk Apps installed for a group
      effect: read
      questions:
      - Which Snyk Apps are installed at the group level?
      - Can I see every app install on my Snyk group, with the app details expanded?
      instructions:
      - text: List the Snyk Apps installed for group {group_id}.
        slots:
          group_id: path.group_id
      - text: Show the first {limit} app installs on group {group_id}.
        slots:
          limit: query.limit
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_id}/apps/installs'].post
  update:
    x-apievangelist-phrasing:
      intent: Install a Snyk App for a group
      effect: write
      questions:
      - How do I install a client-credentials Snyk App across a whole group?
      - Can a Snyk App be installed at the group level instead of per organization?
      instructions:
      - text: Install the Snyk App on group {group_id}.
        slots:
          group_id: path.group_id
      - text: Add a group-level install of our unattended Snyk App to group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_id}/apps/installs/{install_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a Snyk App install from a group
      effect: destructive
      questions:
      - How do I uninstall a Snyk App from a group so it loses access?
      - Can I revoke a group's app authorization using the install ID?
      instructions:
      - text: Revoke app install {install_id} from group {group_id}.
        slots:
          install_id: path.install_id
          group_id: path.group_id
      - text: Remove the group-level Snyk App installation {install_id} in group {group_id}.
        slots:
          install_id: path.install_id
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_id}/apps/installs/{install_id}/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Manage the client secret of a group app install
      effect: write
      questions:
      - How do I rotate the client secret for a non-interactive app installed on my group?
      - Can I replace the secret of a group-level Snyk App installation?
      instructions:
      - text: Rotate the client secret for group install {install_id} in group {group_id}.
        slots:
          install_id: path.install_id
          group_id: path.group_id
      - text: Manage the secret on group {group_id}'s app installation {install_id}.
        slots:
          group_id: path.group_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/app_bots'].get
  update:
    x-apievangelist-phrasing:
      intent: List app bots authorized to an org (deprecated)
      effect: read
      questions:
      - Which app bots are authorized on my Snyk organization?
      - Is there still a legacy app bots listing for an org?
      instructions:
      - text: List the app bots authorized to org {org_id} using the deprecated app_bots endpoint.
        slots:
          org_id: path.org_id
      - text: Show the legacy app bots on organization {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/app_bots/{bot_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an app bot's authorization (deprecated)
      effect: destructive
      questions:
      - How do I revoke an app bot from my organization?
      - Can I still remove a legacy app bot by its bot ID?
      instructions:
      - text: Revoke app bot {bot_id} in org {org_id}.
        slots:
          bot_id: path.bot_id
          org_id: path.org_id
      - text: Remove the legacy app bot {bot_id} from organization {org_id}.
        slots:
          bot_id: path.bot_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps'].get
  update:
    x-apievangelist-phrasing:
      intent: List apps created by an org (deprecated endpoint)
      effect: read
      questions:
      - Is there an older endpoint that lists the apps my org created?
      - What does the deprecated org apps listing return compared with app creations?
      instructions:
      - text: List the apps org {org_id} created using the deprecated apps endpoint.
        slots:
          org_id: path.org_id
      - text: Call the legacy app listing for organization {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an app for an org (deprecated endpoint)
      effect: write
      questions:
      - Can I still create an app with name, redirect URIs and scopes through the old apps endpoint?
      - What fields does the deprecated create-app call take?
      instructions:
      - text: Create an app named {name} in org {org_id} with redirect URIs {redirect_uris} and scopes {scopes} via the legacy endpoint.
        slots:
          name: requestBody.name
          org_id: path.org_id
          redirect_uris: requestBody.redirect_uris
          scopes: requestBody.scopes
      - text: Via the legacy endpoint, register {name} in org {org_id} with token TTL {access_token_ttl_seconds}s, redirects {redirect_uris}, scopes {scopes}.
        slots:
          name: requestBody.name
          org_id: path.org_id
          access_token_ttl_seconds: requestBody.access_token_ttl_seconds
          redirect_uris: requestBody.redirect_uris
          scopes: requestBody.scopes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations'].get
  update:
    x-apievangelist-phrasing:
      intent: List Snyk Apps created by an organization
      effect: read
      questions:
      - Which Snyk Apps has my organization built?
      - Can I page through the app creations owned by an org?
      instructions:
      - text: List the Snyk App creations in org {org_id}.
        slots:
          org_id: path.org_id
      - text: Show {limit} apps my organization {org_id} created.
        slots:
          limit: query.limit
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new Snyk App for an organization
      effect: write
      questions:
      - How do I register a new Snyk App under my organization?
      - Can I create an OAuth app owned by a Snyk org?
      instructions:
      - text: Create a new Snyk App in org {org_id}.
        slots:
          org_id: path.org_id
      - text: Register an app creation for organization {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations/{app_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Snyk App by its app ID
      effect: read
      questions:
      - Where can I see the details of one Snyk App my org created?
      - Can I look up a created app's settings by app ID?
      instructions:
      - text: Get Snyk App {app_id} from org {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      - text: Show the app creation {app_id} in organization {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations/{app_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Snyk App by its app ID
      effect: destructive
      questions:
      - How do I permanently delete a Snyk App my org created?
      - Can I remove an app creation using its app ID?
      instructions:
      - text: Delete Snyk App {app_id} from org {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      - text: Remove the app creation {app_id} owned by organization {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations/{app_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a Snyk App's name, redirects or token TTL
      effect: write
      questions:
      - How do I change the redirect URIs of a Snyk App I created?
      - Can I shorten the access token time to live on an app creation?
      instructions:
      - text: Update Snyk App {app_id} in org {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      - text: Rename app creation {app_id} in organization {org_id} and adjust its redirect URIs.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/creations/{app_id}/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Manage the client secret of a Snyk App
      effect: write
      questions:
      - How do I rotate the client secret of a Snyk App my org created?
      - Can I regenerate an app creation's secret by app ID?
      instructions:
      - text: Rotate the client secret for Snyk App {app_id} in org {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      - text: Manage secrets on app creation {app_id} belonging to organization {org_id}.
        slots:
          app_id: path.app_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/installs'].get
  update:
    x-apievangelist-phrasing:
      intent: List Snyk Apps installed for an organization
      effect: read
      questions:
      - Which Snyk Apps are installed on my organization?
      - Can I list org app installs with the app details expanded?
      instructions:
      - text: List the app installs on org {org_id}.
        slots:
          org_id: path.org_id
      - text: Show which third-party apps are installed in organization {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/installs'].post
  update:
    x-apievangelist-phrasing:
      intent: Install a Snyk App for an organization
      effect: write
      questions:
      - How do I install a client-credentials Snyk App into a single organization?
      - Can an unattended Snyk App be installed on just one org?
      instructions:
      - text: Install the Snyk App on org {org_id}.
        slots:
          org_id: path.org_id
      - text: Add an org-level installation of our non-interactive app to organization {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/installs/{install_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a Snyk App install from an organization
      effect: destructive
      questions:
      - How do I uninstall a Snyk App from one organization?
      - Can I revoke an org's app authorization with the install ID?
      instructions:
      - text: Revoke app install {install_id} from org {org_id}.
        slots:
          install_id: path.install_id
          org_id: path.org_id
      - text: Uninstall org-level installation {install_id} in organization {org_id}.
        slots:
          install_id: path.install_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/installs/{install_id}/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Manage the client secret of an org app install
      effect: write
      questions:
      - How do I rotate the secret for a non-interactive app installed on my org?
      - Can I replace the client secret of an organization-level app installation?
      instructions:
      - text: Rotate the client secret for org install {install_id} in org {org_id}.
        slots:
          install_id: path.install_id
          org_id: path.org_id
      - text: Manage the secret on organization {org_id}'s app installation {install_id}.
        slots:
          org_id: path.org_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/{client_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app by client ID (deprecated)
      effect: read
      questions:
      - Can I look up an app by its OAuth client ID?
      - What does the legacy get-app-by-client-id call return?
      instructions:
      - text: Get the app with client ID {client_id} in org {org_id}.
        slots:
          client_id: path.client_id
          org_id: path.org_id
      - text: Fetch app {client_id} from organization {org_id} using the deprecated client-id endpoint.
        slots:
          client_id: path.client_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/{client_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app by client ID (deprecated)
      effect: destructive
      questions:
      - How do I delete an app when I only have its client ID?
      - Can the older client-id endpoint still delete an app?
      instructions:
      - text: Delete the app with client ID {client_id} from org {org_id}.
        slots:
          client_id: path.client_id
          org_id: path.org_id
      - text: Remove app {client_id} in organization {org_id} via the legacy client-id endpoint.
        slots:
          client_id: path.client_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/{client_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an app by client ID (deprecated)
      effect: write
      questions:
      - Can I rename an app or change its redirect URIs using its client ID?
      - What can the deprecated update-app-by-client-id call change?
      instructions:
      - text: Rename the app with client ID {client_id} in org {org_id} to {name}.
        slots:
          client_id: path.client_id
          org_id: path.org_id
          name: requestBody.name
      - text: Set redirect URIs {redirect_uris} and a {access_token_ttl_seconds}-second token TTL on client {client_id} in org {org_id}.
        slots:
          redirect_uris: requestBody.redirect_uris
          access_token_ttl_seconds: requestBody.access_token_ttl_seconds
          client_id: path.client_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/apps/{client_id}/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Manage client secrets for an app (deprecated)
      effect: write
      questions:
      - How do I replace or create a client secret for an app identified by client ID?
      - Which secret modes does the legacy client-id secrets endpoint accept?
      instructions:
      - text: Run secret mode {mode} on the app with client ID {client_id} in org {org_id}.
        slots:
          mode: requestBody.mode
          client_id: path.client_id
          org_id: path.org_id
      - text: Use mode {mode} to manage secret {secret} for client {client_id} in organization {org_id}.
        slots:
          mode: requestBody.mode
          secret: requestBody.secret
          client_id: path.client_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps'].get
  update:
    x-apievangelist-phrasing:
      intent: List Snyk Apps that can act on your behalf
      effect: read
      questions:
      - Which Snyk Apps have I authorized to act as me?
      - What apps currently have access to my Snyk account?
      instructions:
      - text: List the apps that can act on my behalf.
      - text: Show the first {limit} apps I've authorized on my account.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps/installs'].get
  update:
    x-apievangelist-phrasing:
      intent: List Snyk App installs for the current user
      effect: read
      questions:
      - Which Snyk App installations belong to my user account?
      - Can I see my personal app installs with app details expanded?
      instructions:
      - text: List my personal Snyk App installs.
      - text: Show my user-level app installations with the app expanded using {expand}.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps/installs/{install_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke one of your app installs by install ID
      effect: destructive
      questions:
      - How do I revoke a Snyk App I installed for myself, by its install ID?
      - Can I remove my own app installation without touching org installs?
      instructions:
      - text: Revoke my app install {install_id}.
        slots:
          install_id: path.install_id
      - text: Remove personal installation {install_id} from my account.
        slots:
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps/{app_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an app's access to you by app ID
      effect: destructive
      questions:
      - How do I stop a Snyk App from acting on my behalf?
      - Can I revoke an app's access to my account using its app ID?
      instructions:
      - text: Revoke app {app_id}'s access to my account.
        slots:
          app_id: path.app_id
      - text: Deauthorize the app with ID {app_id} for me.
        slots:
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps/{app_id}/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List your active OAuth sessions for an app
      effect: read
      questions:
      - Which OAuth sessions does a Snyk App currently have open for me?
      - Can I see how many active sessions an app holds on my account?
      instructions:
      - text: List my active sessions for app {app_id}.
        slots:
          app_id: path.app_id
      - text: Show open OAuth sessions app {app_id} has with me.
        slots:
          app_id: path.app_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/self/apps/{app_id}/sessions/{session_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke one active session of a Snyk App
      effect: destructive
      questions:
      - How do I end a single OAuth session an app has with me?
      - Can I kill one app session while keeping the app authorized?
      instructions:
      - text: Revoke session {session_id} of app {app_id}.
        slots:
          session_id: path.session_id
          app_id: path.app_id
      - text: End app {app_id}'s OAuth session {session_id} on my account.
        slots:
          app_id: path.app_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'